Requests and responses

Every v3 endpoint follows the same conventions. Code written against one resource works the same way against the others.

Requests

Send JSON bodies with Content-Type: application/json.
Identifiers are integers. Every candidate id is your company's candidate id, the id returned by /v3/candidates.
Request bodies are validated strictly. An unknown enum value, a wrong type, or a missing required field returns 422 validation_error with one details entry per field.

Response envelope

A single resource is wrapped in data:

{ "data": { "id": 1042, "name": "Berlin HQ" } }

A list adds nextCursor:

{ "data": [ { "id": 1042 }, { "id": 1043 } ], "nextCursor": "eyJpZCI6MTA0M30" }

No endpoint returns a bare object or array. New top-level fields may appear next to data in the future.

Status codes

Method	Success
`GET`	`200 OK`
`POST` (create)	`201 Created`, with the created resource
`PATCH`	`200 OK`, with the updated resource
`PUT` (action)	`200 OK`, with the updated resource
`DELETE`	`204 No Content`, with an empty body

Error status codes are listed in Errors.

Updates

PATCH is a partial update. A field you send replaces its value, and a field you omit is unchanged. Two rules apply:

Nested objects and arrays are replaced in full. Send the complete value, for example the whole address of an office.
null clears an optional field.

Data conventions

Topic	Convention
Field names	camelCase, for example `phoneNumber`, `createdAt`.
Enum values	`UPPER_SNAKE_CASE`, for example `APPLICATION_REVIEW`. The same values are accepted on input and returned on output.
Timestamps	ISO 8601 in UTC, for example `2026-10-05T09:32:40.705Z`.
Dates	ISO 8601 date, for example `2026-11-01`.
Countries	ISO 3166-1 alpha-2, for example `DE`.
Currencies	ISO 4217, for example `EUR`.
Empty values	A nullable field with no value is `null`, never an empty string. An empty list is `[]`.
Related records	Referenced by id, for example `jobId`. A small summary is embedded where it saves a request, such as `candidate` on an application.

File downloads

Document and file url fields are pre-signed links, valid for one hour. They need no Authorization header. Download the file when you read the record, or read the record again for a fresh link.

Not found

A record that does not exist, was deleted, or belongs to another company returns 404. The response never reveals whether an id exists elsewhere.