Fazer a triagem de um candidato

Atualizado 29 de setembro de 2026

Uma triagem é uma entrevista com IA construída a partir de um dos seus modelos de triagem. O candidato faz a triagem quando lhe convém, e os resultados voltam para a Orbit. Os recrutadores enviam triagens a partir da Orbit. Esta página serve para enviá-las a partir do seu próprio sistema, por exemplo quando uma mudança de etapa no seu ATS deve convidar o candidato sem que ninguém abra a Orbit.

O que precisa

• Uma chave com o âmbito Triagem, criada em Orbit → Definições → Chaves de API. É um âmbito à parte: uma chave que lê ou gere vagas responde 403 aqui, e uma chave de triagem não consegue ler vagas.
• Um anúncio gerido. A triagem faz parte de gerir um anúncio, que um recrutador ativa na Orbit. Num anúncio que não é gerido, o pedido responde 409 com ad_not_managed.
• Três ids: o jobId da vaga, o id do candidato nessa vaga e o templateId de um dos seus modelos de triagem ativos.

export ORBIT_SCREENING_KEY="…uma chave com o âmbito Triagem…"

Convidar o candidato

curl -X POST https://api.wipperoz.com/v1/jobs/job_01J8Z3K9Q0EXAMPLE/candidates/app_01J9B2C3D4EXAMPLE/screening \
  -H "Authorization: Bearer $ORBIT_SCREENING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_01J9C3D4E5EXAMPLE",
    "completeBy": "2026-10-02T00:00:00.000Z",
    "message": "Obrigado pela sua candidatura. Demora cerca de quinze minutos.",
    "language": "pt"
  }'

• templateId é o único campo obrigatório. Tem de ser um dos modelos de triagem ativos da sua conta.
• completeBy é o prazo, como data ISO 8601. Sem ele, o candidato tem sete dias.
• message é uma nota que o candidato lê no convite, até 1000 caracteres.
• language é en, es, fr ou pt, e en por omissão. É o idioma do email de convite quando o candidato é contactado por email.

Um campo que a rota não conhece responde 400, como em todas as escritas desta API.

{
  "screening": {
    "screeningId": "8d3f6a2e-4b1c-4f0a-9e7d-2c5b8a1f0e3d",
    "jobId": "job_01J8Z3K9Q0EXAMPLE",
    "candidateId": "app_01J9B2C3D4EXAMPLE",
    "templateId": "tpl_01J9C3D4E5EXAMPLE",
    "status": "invited",
    "deliveryPath": "token",
    "completeBy": "2026-10-02T00:00:00.000Z",
    "requestedAt": "2026-09-25T01:10:00.000Z"
  },
  "billing": "overage",
  "priceCents": 300,
  "currency": "AUD"
}

• deliveryPath diz como o candidato foi contactado, da mesma forma que a Orbit o faz: interview é um pedido de entrevista no seu CV Virtual, e token é um email com uma ligação de uso único. O endereço de email nunca é devolvido.
• billing é included quando a triagem usou uma das incluídas no anúncio, e overage quando é uma adicional.
• priceCents é o preço por triagem do modelo, fixado neste momento, em unidades menores e sem GST. Uma triagem adicional só é faturada a esse preço se o candidato a concluir: se nunca a fizer, não custa nada.

De onde vêm os ids

• jobId é o id que a vaga recebeu quando a criou, ou o que GET /v1/jobs devolve a uma chave que lê vagas.
• O id do candidato é o que a Orbit usa para ele nessa vaga. É a última parte do endereço da página dele na Orbit: …/jobs/{jobId}/candidates/{candidateId}.

Uma triagem de cada vez

Um candidato tem uma triagem por vaga de cada vez. Enquanto houver uma aberta, um segundo pedido é recusado, e a recusa traz a triagem aberta em error.screening, para que o seu sistema retome essa em vez de enviar outro convite.

Isso também torna segura uma repetição depois de um tempo esgotado. Se o primeiro pedido passou, a repetição é recusada com a triagem que ele criou, e o candidato é convidado uma só vez.

Quando é recusada

Um pedido recusado não envia nada e não deixa nada reservado.

Um 429 aqui diz respeito ao candidato, não à sua chave, por isso repetir mais cedo não ajuda. A rota não está sujeita ao limite de pedidos por minuto e não envia cabeçalhos X-RateLimit-*: o que a limita é uma triagem aberta por candidato e por vaga, e o limite mensal de triagens adicionais.

Referência