To connect your ATS or product to Coodesh assessments, use the REST API with an integration key from your workspace. With it, your system lists the published assessments, invites people to take them and receives the results.

Environments and links

Resource	Address
Official API documentation	https://coodesh.com/docs
Production	https://api.coodesh.com
AI assistants (MCP)	How to connect your AI assistant (MCP)

Authentication

Send the integration key on every request, in the headers below:

Header	Value
X-API-KEY	<your integration key>
Content-Type	application/json

Integration flow

Your system fetches the available assessments (GET /assessments/ats).
For each person, your system creates an attempt (POST /assessments/ats/attempts) and receives the assessment link.
Coodesh sends the invitation by e-mail. If you send disable_email: true, no invitation is sent and your system delivers the link to the person.
The person takes the assessment.
On every status change, Coodesh calls the webhook_url you provided. The result can also be fetched at any time.

Endpoints

The paths below are relative to https://api.coodesh.com.

List assessments

GET /assessments/ats

Lists the published assessments in the key's workspace, newest first. Optional parameters:

search: text to search assessments.
offset: how many items to skip. Default: 0.
limit: items per page. Default: 20; maximum: 2000.

Response

{
  "offset": 0,
  "total": 1,
  "limit": 20,
  "payload": [
    {
      "assessment_id": "6707e51d867d313ecdd5f456",
      "name": "Desenvolvimento Backend",
      "description": "Avaliar lógica de programação e arquitetura",
      "default_locale": "pt",
      "duration": 5,
      "duration_unit": "hour",
      "subaccount_ids": [],
      "assess_team": false,
      "questions": [
        {
          "name": "Teste básico de lógica",
          "description": "Crie uma classe que implemente os métodos abaixo...",
          "type": "freecoding",
          "type_formatted": "Programação livre",
          "level": "beginner",
          "level_formatted": "Iniciante",
          "duration": 30,
          "duration_unit": "minute"
        },
        {
          "name": "Infraestrutura multiusuário e multitenant",
          "description": "Desenhe e explique uma arquitetura...",
          "type": "whiteboard",
          "type_formatted": "Quadro branco",
          "level": "advanced",
          "level_formatted": "Avançado",
          "duration": 5,
          "duration_unit": "hour"
        }
      ]
    }
  ]
}

Create an attempt

POST /assessments/ats/attempts

Creates an attempt of the chosen assessment for a person and returns the link to take it. Language and deadline follow the assessment settings.

Field	Type	Required	Description
`name`	string	Yes	Person's name
`email`	string	Yes	Person's e-mail
`user_id`	string	Yes	Person's identifier in your system
`assessment_id`	string	Yes	Assessment, as returned by the list
`company_id`	string	Yes	Company identifier in your system
`job_id`	string	Yes	Job identifier in your system
`callback_url`	URL	Yes	Return address in your system, such as the application page
`webhook_url`	URL	No	Address that receives status changes
`disable_email`	boolean	No	When true, Coodesh sends neither the invitation nor the result e-mail to the person. Default: false

If the assessment has a return address set up in Coodesh, it takes precedence over the one you send. If there is already an invitation not yet started for the same person and assessment, the API reuses that attempt.

Request

{
  "name": "Ana Silva",
  "email": "ana.silva@exemplo.com",
  "user_id": "b12002e0-afc4-11ee-ac51-1fb9ace11428",
  "company_id": "d5cf6e60-f2f5-11e7-9747-838fbc80281c",
  "job_id": "54046020-aec4-11ee-a01d-174ac5115722",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "callback_url": "https://empresa.seuats.com/candidaturas/123",
  "webhook_url": "https://api.seuats.com/webhooks/coodesh",
  "disable_email": true
}

Response

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "attempt_url": "https://coodesh.com/pt/assessments/{token}"
}

Get a result

GET /assessments/ats/attempts/{attemptId}

Returns the status and result of an attempt by its attempt_id. In results, each item is one question of the assessment.

Response

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "finished",
  "status_formatted": "Finalizado",
  "description": "Este é o resultado da sua avaliação Desenvolvimento Backend",
  "score": 62,
  "score_type": "percentage",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "finished": "2026-09-26T18:50:25.575Z",
  "invite_link": "https://coodesh.com/pt/assessments/{token}",
  "public_link": "https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}",
  "result_talent_link": "https://coodesh.com/pt/assessments/results/66df68adc308c0ef4ee945f7",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com",
  "proctoring": {
    "devices": 1,
    "locations": 2,
    "fullscreen_exits": 0,
    "tab_exits": 3,
    "copy_paste_count": 0,
    "devtools_open_count": 0,
    "last_location": "BR",
    "last_device_type": "desktop",
    "last_browser": "Chrome",
    "last_os": "macOS",
    "severity_category": "none",
    "severity_category_formatted": "Nenhuma"
  },
  "results": [
    {
      "score": 80,
      "score_type": "percentage",
      "title": "Teste básico de lógica",
      "description": "Programação livre",
      "date": "2026-09-26"
    },
    {
      "score": 44,
      "score_type": "percentage",
      "title": "Infraestrutura multiusuário e multitenant",
      "description": "Quadro branco",
      "date": "2026-09-26"
    }
  ],
  "company_result_string": "Ana Silva obteve 62% de aproveitamento na avaliação Desenvolvimento Backend.\nTestes:\n80% - Teste básico de lógica - Programação livre\n44% - Infraestrutura multiusuário e multitenant - Quadro branco\nAtividades suspeitas: Nenhuma\nEnviada em: 15:47 26 set, 2026 GMT-03:00\nFinalizado em: 15:50 26 set, 2026 GMT-03:00\nRelatório: https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}"
}

Webhook

If you provide a webhook_url when creating the attempt, Coodesh sends a POST with a JSON body to that address whenever the attempt status changes:

Started: the person began the assessment and has not finished it yet.
Expired: the deadline passed without the person finishing the assessment.
Finished: the person completed the assessment and the result is available.
Blocked: the person completed the assessment, but the result is locked because the workspace has no credits left.

Finished and blocked events carry the score, the links and the integrity summary. For the score of each question, fetch the result with GET /assessments/ats/attempts/{attemptId}.

Started

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "started",
  "status_formatted": "Iniciado",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com"
}

Expired

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "expired",
  "status_formatted": "Expirado",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "expired": "2026-09-27T18:47:50.183Z",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com"
}

Finished

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "finished",
  "status_formatted": "Finalizado",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com",
  "description": "Este é o resultado da sua avaliação Desenvolvimento Backend",
  "score": 62,
  "score_type": "percentage",
  "finished": "2026-09-26T18:50:25.575Z",
  "public_link": "https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}",
  "result_talent_link": "https://coodesh.com/pt/assessments/results/66df68adc308c0ef4ee945f7",
  "proctoring": {
    "devices": 1,
    "locations": 2,
    "fullscreen_exits": 0,
    "tab_exits": 3,
    "copy_paste_count": 0,
    "devtools_open_count": 0,
    "last_location": "BR",
    "last_device_type": "desktop",
    "last_browser": "Chrome",
    "last_os": "macOS",
    "severity_category": "none",
    "severity_category_formatted": "Nenhuma"
  },
  "results": [
    {
      "score": 62,
      "title": "Desenvolvimento Backend",
      "score_type": "percentage",
      "date": "2026-09-26"
    }
  ],
  "company_result_string": "Ana Silva obteve 62% de aproveitamento na avaliação Desenvolvimento Backend.\nTestes:\n80% - Teste básico de lógica - Programação livre\n44% - Infraestrutura multiusuário e multitenant - Quadro branco\nAtividades suspeitas: Nenhuma\nEnviada em: 15:47 26 set, 2026 GMT-03:00\nFinalizado em: 15:50 26 set, 2026 GMT-03:00\nRelatório: https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}"
}

Rate limit

There is a per-second request limit, per key and per workspace. On a 429, wait the number of seconds given in the Retry-After-short header (per-key limit) or Retry-After-long (per-workspace limit) and retry.

Error codes

Code	Meaning
400 - Bad Request	Invalid or malformed data, or assessment and attempt not found in the key's workspace.
401 - Unauthorized	Missing or invalid integration key.
403 - Forbidden	The key has no access to the requested resource.
429 - Too Many Requests	Request limit reached.
500 - Internal Server Error	Unexpected server error. If it persists, write to help@coodesh.com.

Coodesh Job Feed: XML job feed development guide

I want to integrate my product with Coodesh via API

Environments and links

Authentication

Integration flow

Endpoints

List assessments

Response

Create an attempt

Request

Response

Get a result

Response

Webhook

Started

Expired

Finished

Rate limit

Error codes