Passar para o conteúdo principal

Endpoint Candidato: Desclassificar e Excluir [PUT/DELETE]

W
Escrito por William Coelho

Desclassificar candidato em uma vaga

[PUT] https://api.quickin.io/accounts/{account_id}/placements/{placement_id}/disqualify

Requalificar candidato em uma vaga

[PUT] https://api.quickin.io/accounts/{account_id}/placements/{placement_id}/requalify

Excluir candidato

[DELETE] https://api.quickin.io/accounts/{account_id}/candidates/{candidate_id}


Autenticação

Enviar o token no header da requisição (o Content-Type é necessário apenas quando houver corpo):

Authorization: Bearer {token} Content-Type: application/json


Parâmetros de URL

Parâmetro

Tipo

Exemplo

Descrição

Limites / Observações

account_id

String

64f1a2b3c4d5e6f7a8b9c0d1

ID da conta

Obrigatório. Mesmo valor usado nos demais endpoints.

placement_id

String

6700aa11bb22cc33dd44ee55

ID da candidatura (candidato + vaga)

Obrigatório em /placements. Ver lista de candidaturas do candidato. Deve pertencer à conta, senão 404 NotFound.

candidate_id

String

66aa11bb22cc33dd44ee55ff

ID do candidato

Obrigatório em /candidates. Deve ser um ObjectId válido, senão 400 ValidationError.


Campos principais (body do PUT /disqualify)

Campo

Tipo

Exemplo

Descrição

Limites / Observações

disqualify_reason_id

String

65b0c1d2e3f4a5b6c7d8e9f0

ID do motivo de desclassificação

Obrigatório. Precisa ser um motivo cadastrado na conta. Ver lista de motivos de desclassificação. Nenhum outro campo é aceito no body.

Atenção sobre o comportamento de cada operação

Desclassificar altera a candidatura para status: "disqualified" e grava o disqualify_reason_id. O candidato permanece na etapa em que estava. A operação é idempotente: desclassificar uma candidatura já desclassificada devolve 200 sem alterar o motivo já gravado.

Desclassificar dispara automações. Se o plano da conta tiver a funcionalidade de gatilhos automatizados (automated_triggers), as ações configuradas na etapa para o evento "desclassificar" são executadas (e-mail ao candidato, tarefas etc.). Também é gerada a notificação interna "Candidato desclassificado" para a equipe da vaga.

Requalificar volta a candidatura para status: "qualified" e limpa o disqualify_reason_id. Também é idempotente.

Excluir candidato é irreversível. Remove o candidato e, em cascata: candidaturas em todas as vagas, anexos, notas, tarefas, avaliações, eventos de agenda, e-mails, formulários e entrevistas em vídeo respondidos, histórico de movimentações e notificações. Conversas de WhatsApp ligadas ao candidato são preservadas, mas deixam de apontar para ele. Se o candidate_id não existir ou não pertencer à conta, a API responde 200 com {} da mesma forma.

Nenhuma destas rotas aceita operação em lote. Para desclassificar ou excluir vários candidatos, faça uma chamada por candidatura ou por candidato.


Exemplo de desclassificação [PUT]

Requisição:

PUT https://api.quickin.io/accounts/64f1a2b3c4d5e6f7a8b9c0d1/placements/6700aa11bb22cc33dd44ee55/disqualify

Body:

{
"disqualify_reason_id":"65b0c1d2e3f4a5b6c7d8e9f0"
}

Resposta 200 OK (candidatura atualizada):

{
"_id":"6700aa11bb22cc33dd44ee55",
"status":"disqualified",
"hired":false,
"new":false,
"stage_date":"2025-10-02T14:21:07.512Z",
"candidate_id":"66aa11bb22cc33dd44ee55ff",
"job_id":"6650ffee11dd22cc33bb44aa",
"stage_id":{
"_id":"6650ffee11dd22cc33bb44bb",
"type":"interview",
"name":"Entrevista com RH"
},
"author_user_id":"63a0b1c2d3e4f5a6b7c8d9e0",
"application_answers":[],
"hired_date":null,
"disqualify_reason_id":"65b0c1d2e3f4a5b6c7d8e9f0",
"created_at":"2025-09-28T11:03:44.901Z",
"updated_at":"2025-10-10T18:45:12.377Z"
}

Exemplo de requalificação [PUT]

Requisição:

PUT https://api.quickin.io/accounts/64f1a2b3c4d5e6f7a8b9c0d1/placements/6700aa11bb22cc33dd44ee55/requalify

Resposta 200 OK: mesma estrutura acima, com:

{
"status":"qualified",
"disqualify_reason_id":null
}

Exemplo de exclusão de candidato [DELETE]

Requisição:

DELETE https://api.quickin.io/accounts/64f1a2b3c4d5e6f7a8b9c0d1/candidates/66aa11bb22cc33dd44ee55ff

Resposta 200 OK:

{}

Dependências

Alguns campos dependem de listas auxiliares da API.

Lista de motivos de desclassificação

[GET] https://api.quickin.io/accounts/{account_id}/disqualify-reasons

Header:

Authorization: Bearer {token}

Retorna os motivos cadastrados na conta, cada um com _id, name, created_at e updated_at.

Respondeu à sua pergunta?