Para integrar seu ATS ou produto às avaliações da Coodesh, use a API REST com uma chave de integração da sua área de trabalho. Com ela, seu sistema lista as avaliações publicadas, convida pessoas para respondê-las e recebe os resultados.
Ambientes e links
Recurso | Endereço |
Documentação oficial da API | |
Produção | |
Assistentes de IA (MCP) |
Autenticação
Envie a chave de integração em todas as requisições, nos cabeçalhos abaixo:
Cabeçalho | Valor |
X-API-KEY | <sua chave de integração> |
Content-Type | application/json |
Fluxo da integração
Seu sistema consulta as avaliações disponíveis (
GET /assessments/ats).Para cada pessoa, seu sistema cria uma tentativa (
POST /assessments/ats/attempts) e recebe o link da avaliação.A Coodesh envia o convite por e-mail. Se você enviar
disable_email: true, o convite não é enviado e seu sistema entrega o link à pessoa.A pessoa responde à avaliação.
A cada mudança de status, a Coodesh chama o
webhook_urlinformado. O resultado também pode ser consultado a qualquer momento.
Endpoints
Os caminhos abaixo são relativos a https://api.coodesh.com.
Listar avaliações
GET /assessments/ats
Lista as avaliações publicadas na área de trabalho da chave, das mais recentes para as mais antigas. Parâmetros opcionais:
search: texto para buscar avaliações.offset: quantos itens pular. Padrão: 0.limit: itens por página. Padrão: 20; máximo: 2000.
Resposta
{
"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"
}
]
}
]
}
Criar uma tentativa
POST /assessments/ats/attempts
Cria uma tentativa da avaliação escolhida para uma pessoa e devolve o link para respondê-la. O idioma e o prazo seguem a configuração da avaliação.
Campo | Tipo | Obrigatório | Descrição |
| string | Sim | Nome da pessoa |
| string | Sim | E-mail da pessoa |
| string | Sim | Identificador da pessoa no seu sistema |
| string | Sim | Avaliação, conforme a listagem |
| string | Sim | Identificador da empresa no seu sistema |
| string | Sim | Identificador da vaga no seu sistema |
| URL | Sim | Endereço de retorno no seu sistema, como a página da candidatura |
| URL | Não | Endereço que recebe as mudanças de status |
| boolean | Não | Quando true, a Coodesh não envia o convite nem o e-mail de resultado à pessoa. Padrão: false |
Se a avaliação tiver um endereço de retorno configurado na Coodesh, ele prevalece sobre o enviado. Se já existir um convite ainda não iniciado para a mesma pessoa e avaliação, a API reaproveita essa tentativa.
Requisição
{
"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
}
Resposta
{
"attempt_id": "66df68adc308c0ef4ee945f7",
"attempt_url": "https://coodesh.com/pt/assessments/{token}"
}
Obter um resultado
GET /assessments/ats/attempts/{attemptId}
Devolve o status e o resultado de uma tentativa a partir do attempt_id. Em results, cada item corresponde a uma questão da avaliação.
Resposta
{
"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
Se você informar o webhook_url ao criar a tentativa, a Coodesh envia um POST com um JSON a esse endereço sempre que o status da tentativa mudar:
Iniciado (started): a pessoa começou a avaliação e ainda não terminou.
Expirado (expired): o prazo terminou sem que a pessoa concluísse a avaliação.
Finalizado (finished): a pessoa concluiu a avaliação e o resultado está disponível.
Bloqueado (blocked): a pessoa concluiu a avaliação, mas o resultado está bloqueado por falta de créditos na área de trabalho.
Os eventos de finalizado e bloqueado trazem a nota, os links e o resumo de integridade. Para ver a nota de cada questão, consulte o resultado pelo endpoint GET /assessments/ats/attempts/{attemptId}.
Iniciado (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"
}
Expirado (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"
}
Finalizado (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}"
}
Limite de requisições
Existe um limite de requisições por segundo, por chave e por área de trabalho. Ao receber o código 429, aguarde os segundos indicados no cabeçalho Retry-After-short (limite por chave) ou Retry-After-long (limite por área de trabalho) e repita a chamada.
Códigos de erro
Código | Significado |
400 - Bad Request | Dados inválidos ou fora do padrão, ou avaliação e tentativa não encontradas na área de trabalho da chave. |
401 - Unauthorized | Chave de integração ausente ou inválida. |
403 - Forbidden | A chave não tem acesso ao recurso solicitado. |
429 - Too Many Requests | Limite de requisições atingido. |
500 - Internal Server Error | Erro inesperado no servidor. Se persistir, escreva para help@coodesh.com. |
Vídeo: a integração com o seu ATS
Em menos de dois minutos, o caminho inteiro da integração com o seu ATS: da chave de integração ao resultado chegando na candidatura.