Resumen de la API de Candidatos

La API de Candidatos proporciona acceso completo a la información de candidatos, incluyendo detalles personales, historial de evaluaciones, datos de currículum y análisis de habilidades.

Endpoints Disponibles

Operaciones Principales de Candidatos

Endpoint	Método	Descripción
/candidates/	GET	Obtener todos los candidatos de una organización
/candidates/{candidate_id}	GET	Obtener información detallada del candidato
/candidates/{candidate_id}/resume	GET	Obtener datos del currículum e información de perfil del candidato
/candidates/by_email/{candidate_email}	GET	Obtener información detallada del candidato por correo electrónico

Resumen de endpoints de candidatos disponibles y sus relaciones

Características Principales

Gestión de Candidatos

• Obtener todos los candidatos asociados con tu organización
• Acceder a perfiles detallados incluyendo información personal e historial de evaluaciones
• Ver información del currículum con propiedades analizadas y habilidades extraídas
• Buscar por correo electrónico para búsqueda rápida de candidatos

Datos Disponibles

Información Personal

• Nombre, correo electrónico y número de teléfono
• Detalles de contacto y datos demográficos básicos

Datos de Evaluación

• Todas las evaluaciones a las que el candidato ha sido invitado o completado
• Estado de evaluación e información de finalización
• Puntuaciones y evaluaciones generadas por IA
• Resultados de pruebas y métricas de rendimiento

Análisis de Currículum

• Propiedades del currículum analizadas (ubicación, antigüedad, título del trabajo)
• Habilidades extraídas con años de experiencia
• Historial laboral y detalles de empleo
• Contenido de texto del currículum para análisis detallado

Casos de Uso Comunes

Gestión de Pipeline de Talento

• Obtener vista general de todos los candidatos en tu pipeline de reclutamiento
• Seguir el progreso de candidatos a través de diferentes evaluaciones
• Monitorear tasas de finalización y estado de evaluaciones

Evaluación de Candidatos

• Acceder a perfiles detallados de candidatos para preparación de entrevistas
• Revisar resultados de evaluaciones y puntuaciones generadas por IA
• Analizar coincidencias de habilidades y experiencia

Procesamiento de Currículums

• Extraer y analizar información de currículums automáticamente
• Obtener datos estructurados de currículums subidos
• Acceder tanto al texto crudo del currículum como a propiedades analizadas

Reportes y Analítica

• Generar reportes sobre rendimiento de candidatos
• Analizar tendencias en habilidades y experiencia de candidatos
• Seguir tasas de finalización y éxito de evaluaciones

Paginación y Límites

Soporte de Paginación

• Los resultados están paginados con un máximo de 500 candidatos por página
• Usa el parámetro page para navegar a través de páginas de resultados
• La respuesta incluye metadatos de paginación (total, page, num_pages, page_size)

Ejemplo de Respuesta de Paginación

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

Autenticación y Permisos

Todos los endpoints de candidatos requieren:

• Clave API válida para autenticación
• Membresía organizacional - los candidatos deben ser parte de evaluaciones en tu organización
• Permisos apropiados para acceder a datos de candidatos

Control de Acceso

• Solo puedes acceder a candidatos que son parte de evaluaciones en tu organización
• Intentar acceder a candidatos de otras organizaciones resultará en un error 403
• Candidatos eliminados o inactivos pueden no aparecer en los resultados

Flujo de autenticación y permisos para endpoints de candidatos

Formatos de Respuesta

Estructura de Respuesta Estándar

Todos los endpoints de candidatos devuelven respuestas JSON con estructura consistente:

• Información personal en formato estandarizado
• Datos de evaluación con información de estado y puntuación
• Metadatos incluyendo marcas de tiempo e identificadores
• Manejo de errores con mensajes de error detallados

Campos de Respuesta Comunes

• id: Identificador único del candidato
• name: Nombre completo del candidato
• email: Dirección de correo electrónico principal
• phone: Número de teléfono de contacto
• assessments: Array de información de evaluaciones
• created_at/updated_at: Información de marcas de tiempo

Manejo de Errores

Respuestas de error comunes que puedes encontrar:

Código de Estado	Descripción	Causas Comunes
403	No autorizado	Candidato no está en tu organización
404	No encontrado	ID de candidato o correo electrónico inválido
422	Error de Validación	Parámetros inválidos o formato de solicitud
500	Error interno del servidor	Error del sistema, contacta soporte