Response Structure

Response Format

Responses are in JSON format with the Content-Type: application/json header.

Special Fields

The following fields have special meaning in all API responses:

`_status`

Response status:

"OK": Data was extracted correctly
"INVALID": Request parameters are invalid (HTTP status remains 200)

{
  "_status": "OK",
  "data": { ... }
}

`_self`

URI of the current resource.

At the root of the response: corresponds to the request URL
In a nested object: URL to obtain all data for this resource

{
  "_self": "/restapi/v1/job/42",
  "candidate": {
    "_self": "/restapi/v1/candidate/123"
  }
}

`_schema`

URI of the resource description in JSON-Schema format. This URL provides a comprehensive and up-to-date description of the resource schema.

{
  "_schema": "/restapi/schemav1/job"
}

Schemas are automatically updated with the API and are therefore more accurate than this documentation.

`_actions`

List of possible actions on the current data. This field is only provided when actions are available. Content depends on user permissions.

{
  "_actions": [
    {
      "_self": "/restapi/v1/note",
      "doc": "Add a new note",
      "method": "POST"
    }
  ]
}

`_next`

URI of the next page for paginated resources. If this field is empty or absent, you’ve reached the last page.

{
  "_next": "/restapi/v1/job?pagecursor=42"
}

`items`

List containing response elements for collections.

{
  "_self": "/restapi/v1/job",
  "_next": "/restapi/v1/job?pagecursor=10",
  "items": [
    {
      "id": 1,
      "title": "Full-Stack Developer"
    },
    {
      "id": 2,
      "title": "Project Manager"
    }
  ]
}

Error Handling

Validation Errors

When _status equals "INVALID", an invalid field details the errors:

{
  "_status": "INVALID",
  "invalid": {
    "candidate_id": {
      "code": null,
      "message": "Permission denied"
    },
    "organisation_id": {
      "code": null,
      "message": "Permission denied"
    }
  }
}

HTTP Codes

The API uses standard HTTP codes:

200: Success (also check _status)
307: Temporary redirect (e.g., CV download)
404: Resource not found
401: Authentication required
403: Access denied
429: Too Many Requests (45 req/min per IP limit exceeded)
500: Server error

Complete Response Example

{
  "_status": "OK",
  "_self": "/restapi/v1/job/42",
  "_schema": "/restapi/schemav1/job",
  "id": 42,
  "title": "Full-Stack Developer",
  "status": "OPEN",
  "applications": {
    "_self": "/restapi/v1/job/42/application"
  },
  "process": {
    "_self": "/restapi/v1/process/72",
    "id": 72
  }
}

Introduction

Getting Started

API Architecture

Webhooks

Response Format

Special Fields

`_status`

`_self`

`_schema`

`_actions`

`_next`

`items`

Error Handling

Validation Errors

HTTP Codes

Complete Response Example

​Response Format

​Special Fields

​_status

​_self

​_schema

​_actions

​_next

​items

​Error Handling

​Validation Errors

​HTTP Codes

​Complete Response Example

Response Format

Special Fields

`_status`

`_self`

`_schema`

`_actions`

`_next`

`items`

Error Handling

Validation Errors

HTTP Codes

Complete Response Example