Skip to main content

​
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
  }
}