canonical: https://jentic.com/apis/hurma.work/hurma

# Hurma Work Hurma Public API

Jentic publishes the only available OpenAPI specification for Hurma Public API, keeping it validated and agent-ready. Hurma is an HR management platform whose public API exposes 20 endpoints for managing candidates, employees, departments, and job openings, plus reference dictionaries for cooperation types, languages, and termination reasons. Authentication is performed with OAuth 2.0 authorisation flow or HTTP bearer tokens issued through `/api/v3/oauth/token`, and the API is rate limited to 240 requests per minute. The endpoints support pagination and dictionary lookups so external systems can keep employee records in sync.

## For AI agents

Read and write Hurma candidates, employees, departments, and job openings, and resolve HR dictionary values from an AI agent or backend pipeline.

## Scope

Does not handle payroll runs, time-tracking, or benefits administration - use for candidate, employee, department, and job-opening management only.

## Capabilities

- List, create, and update candidates inside the Hurma recruitment pipeline
- Read and update employee records including department and cooperation type
- Manage departments and resolve their employee membership
- Publish, edit, and close job openings with title, description, and status fields
- Resolve dictionary values for cooperation types, languages, and termination reasons
- Exchange OAuth credentials for an access token via `/api/v3/oauth/token`

## Use cases

### ATS to Hurma Sync

Mirror candidates from an external applicant tracking system into Hurma so that recruiters work in a single tool. POST new applications to `/api/v3/candidates`, PATCH on status changes, and reuse dictionary lookups for languages and cooperation types so the data conforms to Hurma's reference data. Useful for teams running a separate sourcing tool but standardising hiring data in Hurma.

Example prompt: POST `/api/v3/candidates` with the candidate first name, last name, email, and cooperation_type id.

### Employee Directory Sync

Keep an internal directory or SSO group structure aligned with Hurma's employee and department data. The `/api/v3/employees` and `/api/v3/departments` endpoints support listing and updating, and dictionary endpoints provide stable ids for cooperation types and termination reasons. Run the sync nightly or on webhook triggers to keep downstream systems consistent.

Example prompt: GET `/api/v3/employees` with page=1 and reconcile against the local SSO directory.

### Job Board Distribution

Pull active job openings from Hurma and republish them to a careers site, LinkedIn, or third-party job board. The `/api/v3/job-openings` endpoints expose title, description, and status fields, and OAuth bearer tokens scope access to the integration. Combined with a publishing API like Greenhouse or Workable's job board, the workflow is fully automated.

Example prompt: GET `/api/v3/job-openings` filtered to status=open and republish each to the careers site.

### AI Agent HR Assistant

Give an HR assistant agent direct, scoped access to Hurma so it can answer questions like 'how many open roles do we have' or 'who is in the engineering department'. Through Jentic the agent searches for the operation, loads the input schema, and executes - the OAuth bearer token stays in your Jentic One instance so prompt injection cannot leak it.

Example prompt: Search Jentic for 'list open job openings', load the Hurma `/api/v3/job-openings` schema, and execute with status=open.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v3/oauth/token` | Exchange credentials for an access token |
| GET | `/api/v3/candidates` | List candidates |
| GET | `/api/v3/employees` | List employees |
| GET | `/api/v3/departments` | List departments |
| GET | `/api/v3/job-openings` | List job openings |
| GET | `/api/v3/dictionaries/cooperation-types` | List cooperation types |
| GET | `/api/v3/dictionaries/languages` | List languages |

## Key resources

- **Candidates** — Create, list, and update recruitment candidates
- **Employees** — List and update employee records and assignments
- **Departments** — List and update departments and team membership
- **Job Openings** — Create, edit, and close job openings
- **Dictionaries** — Reference lookups for cooperation types, languages, and termination reasons
- **OAuth** — Authorise and exchange tokens for API access

## Why Jentic

- **Setup:** Wiring the Hurma Public API by hand means running its OAuth token exchange, targeting hurma.work, and paging candidate and employee reads yourself. Through Jentic you install once, import the Hurma Public API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** This API serves reads through fixed collection endpoints with filters in the request parameters (`/api/v3/candidates`, `/api/v3/employees`), so limit the agent to the operations it needs, such as listing candidates or departments. You choose the operations it may call, so requesting an OAuth token directly is not included unless you add it.
- **Credential handling:** Your Hurma OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Hurma candidates' or 'list job openings', and Jentic returns the matching Hurma operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **BambooHR API** — BambooHR is a broader HR platform with similar employee, time-off, and recruiting endpoints
- **Personio API** — Personio is a European HR platform with overlapping employee and recruiting APIs
- **Workable API** — Workable handles applicant sourcing while Hurma manages the broader employee record

## FAQ

### Why is there no official OpenAPI spec for Hurma Public API?

Hurma does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Hurma API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Hurma Public API use?

The Hurma API uses OAuth 2.0 with `/api/v3/oauth/authorize` and `/api/v3/oauth/token`, plus HTTP bearer tokens for already-authenticated calls. Through Jentic the credentials sit in the credential vault and Jentic injects the Authorization header at execution time.

### What are the rate limits for the Hurma Public API?

Hurma rate limits the public API to 240 requests per minute. Watch for HTTP 429 responses, batch reads where possible, and stagger writes during nightly syncs to stay within the budget.

### Can I create a candidate through the Hurma API?

Yes. POST to `/api/v3/candidates` with first name, last name, email, and a cooperation_type id resolved from `/api/v3/dictionaries/cooperation-types.` The endpoint returns the created candidate id which you can use for subsequent PATCH calls.

### How do I list open job openings through Jentic?

Search Jentic for 'list open job openings', load the schema for the Hurma GET `/api/v3/job-openings` operation, and execute with status=open. Install with pip install jentic and use the async search, load, and execute pattern.

### How do I resolve dictionary values like cooperation type or language?

Call GET `/api/v3/dictionaries/cooperation-types` or `/api/v3/dictionaries/languages` to retrieve the canonical id and label list, then send the id when creating or updating candidates and employees. This avoids 422 validation errors from sending free-text values.

### Can I limit what my agent is allowed to do with the Hurma Public API?

Yes. Because you run your own self-hosted Jentic One instance, your own rules decide which Hurma operations and credentials the agent may use, so you can grant only the reads it needs, such as listing candidates via GET `/api/v3/candidates` or employees via GET `/api/v3/employees.` The Hurma API serves these as fixed collection endpoints with filters passed in the request parameters, so scoping happens at the operation level rather than through per-record access. Sensitive operations like exchanging credentials at `/api/v3/oauth/token` stay excluded unless you deliberately add them, keeping the agent confined to the exact HR lookups you approve.