Visão Geral da API de Candidatos

A API de Candidatos fornece acesso abrangente às informações de candidatos, incluindo detalhes pessoais, histórico de avaliações, dados de currículo e análise de habilidades.

Endpoints Disponíveis

Operações Principais de Candidatos

Endpoint	Método	Descrição
/candidates/	GET	Obter todos os candidatos de uma organização
/candidates/{candidate_id}	GET	Obter informações detalhadas do candidato
/candidates/{candidate_id}/resume	GET	Obter dados do currículo e informações de perfil do candidato
/candidates/by_email/{candidate_email}	GET	Obter informações detalhadas do candidato por e-mail

Visão geral dos endpoints de candidatos disponíveis e seus relacionamentos

Recursos Principais

Gerenciamento de Candidatos

• Recuperar todos os candidatos associados à sua organização
• Acessar perfis detalhados incluindo informações pessoais e histórico de avaliações
• Visualizar informações do currículo com propriedades analisadas e habilidades extraídas
• Buscar por e-mail para busca rápida de candidatos

Dados Disponíveis

Informações Pessoais

• Nome, e-mail e número de telefone
• Detalhes de contato e dados demográficos básicos

Dados de Avaliação

• Todas as avaliações às quais o candidato foi convidado ou completou
• Status da avaliação e informações de conclusão
• Pontuações e avaliações geradas por IA
• Resultados de testes e métricas de desempenho

Análise de Currículo

• Propriedades do currículo analisadas (localização, senioridade, título do trabalho)
• Habilidades extraídas com anos de experiência
• Histórico profissional e detalhes de emprego
• Conteúdo de texto do currículo para análise detalhada

Casos de Uso Comuns

Gerenciamento de Pipeline de Talentos

• Obter visão geral de todos os candidatos no seu pipeline de recrutamento
• Acompanhar progresso de candidatos através de diferentes avaliações
• Monitorar taxas de conclusão e status de avaliações

Avaliação de Candidatos

• Acessar perfis detalhados de candidatos para preparação de entrevistas
• Revisar resultados de avaliações e pontuações geradas por IA
• Analisar correspondências de habilidades e experiência

Processamento de Currículos

• Extrair e analisar informações de currículos automaticamente
• Obter dados estruturados de currículos enviados
• Acessar tanto o texto bruto do currículo quanto propriedades analisadas

Relatórios e Análises

• Gerar relatórios sobre desempenho de candidatos
• Analisar tendências em habilidades e experiência de candidatos
• Acompanhar taxas de conclusão e sucesso de avaliações

Paginação e Limites

Suporte à Paginação

• Os resultados são paginados com um máximo de 500 candidatos por página
• Use o parâmetro page para navegar através das páginas de resultados
• A resposta inclui metadados de paginação (total, page, num_pages, page_size)

Exemplo de Resposta de Paginação

{
  "candidates": [...],
  "total": 1250,
  "page": 1,
  "num_pages": 3,
  "page_size": 500
}

Autenticação e Permissões

Todos os endpoints de candidatos requerem:

• Chave API válida para autenticação
• Associação organizacional - candidatos devem fazer parte de avaliações na sua organização
• Permissões apropriadas para acessar dados de candidatos

Controle de Acesso

• Você só pode acessar candidatos que fazem parte de avaliações na sua organização
• Tentar acessar candidatos de outras organizações resultará em um erro 403
• Candidatos excluídos ou inativos podem não aparecer nos resultados

Fluxo de autenticação e permissões para endpoints de candidatos

Formatos de Resposta

Estrutura de Resposta Padrão

Todos os endpoints de candidatos retornam respostas JSON com estrutura consistente:

• Informações pessoais em formato padronizado
• Dados de avaliação com informações de status e pontuação
• Metadados incluindo timestamps e identificadores
• Tratamento de erros com mensagens de erro detalhadas

Campos de Resposta Comuns

• id: Identificador único do candidato
• name: Nome completo do candidato
• email: Endereço de e-mail principal
• phone: Número de telefone de contato
• assessments: Array de informações de avaliações
• created_at/updated_at: Informações de timestamp

Tratamento de Erros

Respostas de erro comuns que você pode encontrar:

Código de Status	Descrição	Causas Comuns
403	Não autorizado	Candidato não está na sua organização
404	Não encontrado	ID de candidato ou e-mail inválido
422	Erro de Validação	Parâmetros inválidos ou formato de solicitação
500	Erro interno do servidor	Erro do sistema, entre em contato com o suporte