Guía de la API de precandidatos

Un precandidato es un registro de persona que todavía necesita información adicional antes de que pueda comenzar el procesamiento completo. Usa la API de precandidatos cuando ya sabes qué verificaciones quieres ejecutar, pero aún necesitas que Emptor recoja datos faltantes del candidato. Si quieres que Sol llame al candidato para un screening o a sus referencias, empieza con un precandidato para que Emptor pueda recopilar la información necesaria.

Referencia interactiva de la API

Consulta la referencia interactiva para Crear un precandidato, Obtener precandidatos por person ID y Obtener el esquema del formulario del precandidato.

Cuándo usar precandidatos

Los precandidatos son útiles cuando:

• Tienes información de contacto, como email o teléfono, pero todavía necesitas campos como document_id u otro dato específico del reporte.
• Quieres que Emptor aloje el formulario de recolección de datos en lugar de construir tu propio flujo de intake.
• Quieres identificar el registro de la persona desde el principio y luego continuar el flujo normal de BGC después de que el candidato complete la información faltante.
• Quieres ejecutar flujos como candidate_screening o reference_check, donde el candidato primero debe proporcionar información que se recoge mediante el flujo de precandidato.

Casos de uso específicos por reporte

Algunos reportes dependen del flujo de precandidato como parte del proceso operativo, no solo como una conveniencia:

• candidate_screening: crea un precandidato con un número de phone, porque Emptor debe llamar al candidato como parte del flujo.
• reference_check: usa un flujo de precandidato para que el candidato pueda proporcionar la información de sus referencias antes de que se ejecute la verificación.

Flujo de extremo a extremo

1. Crea el precandidato.
2. Guarda person_id, precandidate_id, form_url y country_code.
3. Opcionalmente consulta el esquema del formulario para saber qué campos le pedirá Emptor al candidato.
4. Comparte el form_url alojado con el candidato, o deja que Emptor Sol recopile la información faltante por teléfono.
5. Haz polling del precandidato hasta que sea enviado.
6. Continúa con los endpoints estándar de personas y reportes usando el mismo person_id.

Regla importante de la solicitud

El esquema público marca solo country_code como obligatorio, pero la descripción del endpoint agrega una regla de negocio: también debes enviar pipeline_id, pipeline_name o una configuración personalizada con reports_enabled y report_settings.

Requisitos específicos del reporte

Si estás creando un precandidato para candidate_screening, incluye un número de phone porque ese flujo requiere llamar al candidato. Si vas a ejecutar reference_check, empieza con un precandidato para que el candidato pueda proporcionar los datos de sus referencias necesarios para la verificación.

Mensajería por WhatsApp

Cuando se proporciona un número de teléfono, Emptor Sol contactará al candidato a través de WhatsApp para recolectar la información faltante. En ese caso, el candidato recibirá por WhatsApp un flujo con las mismas preguntas que también puede responder mediante form_url.

1. Crear un precandidato

Usa POST /precandidate para crear el registro y obtener la URL del formulario alojado.

export API_KEY="your_api_key"
export BASE_URL="https://api.emptor.io/v3"

curl --request POST \
  --url "$BASE_URL/precandidate" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $API_KEY" \
  --data '{
    "country_code": "PE",
    "pipeline_name": "test-pipeline-pe",
    "email": "candidate@example.com",
    "phone": "+51987654321"
  }'

Ejemplo de respuesta:

{
  "person_id": "09a3446b-bae9-4a03-8a4a-fcec24f784e4",
  "precandidate_id": "test-precandidate-id",
  "form_url": "https://dashboard.emptor.io/forms/test-precandidate-id",
  "reports_enabled": ["document_id_status"],
  "report_settings": {},
  "email": "candidate@example.com",
  "phone": "+51987654321",
  "country_code": "PE",
  "precandidate_status": "CREATED",
  "pipeline_id": "0ujsszwN8NRY24YaXiTIE2VWDTS",
  "pipeline_name": "test-pipeline-pe",
  "created_at": "2023-01-01T12:00:00.000000",
  "updated_at": "2023-01-01T12:00:00.000000"
}

Los campos más importantes para persistir son:

• person_id: el identificador que luego usarás con los endpoints estándar de personas y reportes.
• precandidate_id: el identificador del registro de precandidato.
• form_url: el formulario alojado por Emptor para recolectar la información faltante.
• country_code: necesario cuando vuelvas a los endpoints estándar de BGC.

Si no estás usando un pipeline, también puedes crear un precandidato con reports_enabled más report_settings.

2. Consultar el esquema del formulario antes de enviarlo

Usa GET /precandidate/{person_id}/schema/{form_id} para ver exactamente qué campos espera el formulario alojado.

form_id

En la especificación pública de la API, form_id se describe como “Precandidate form ID (same as precandidate_id)”.

export PERSON_ID="09a3446b-bae9-4a03-8a4a-fcec24f784e4"
export PRECANDIDATE_ID="test-precandidate-id"

curl --request GET \
  --url "$BASE_URL/precandidate/$PERSON_ID/schema/$PRECANDIDATE_ID" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

Ejemplo de respuesta:

{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string"
    },
    "city_locode": {
      "description": "2 letter country code and 3 letter city location code.",
      "type": "string"
    }
  },
  "required": ["document_id", "city_locode"]
}

Este endpoint es útil cuando quieres:

• mostrarle al candidato qué información se le solicitará,
• validar tus propios datos precargados antes de enviar el formulario,
• entender qué campos faltan para el pipeline o los reportes seleccionados.

3. Hacer seguimiento de si el precandidato ya fue completado

Usa GET /precandidate/{person_id} para recuperar los registros actuales de precandidato para esa persona.

curl --request GET \
  --url "$BASE_URL/precandidate/$PERSON_ID" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

Ejemplo de respuesta:

[
  {
    "person_id": "09a3446b-bae9-4a03-8a4a-fcec24f784e4",
    "precandidate_id": "test-precandidate-id",
    "form_url": "https://dashboard.emptor.io/forms/test-precandidate-id",
    "reports_enabled": ["document_id_status"],
    "report_settings": {},
    "email": "candidate@example.com",
    "phone": "+51987654321",
    "country_code": "PE",
    "precandidate_status": "SUBMITTED",
    "pipeline_id": "0ujsszwN8NRY24YaXiTIE2VWDTS",
    "pipeline_name": "test-pipeline-pe",
    "created_at": "2023-01-01T12:00:00.000000",
    "updated_at": "2023-01-01T12:10:00.000000"
  }
]

Aquí hay dos detalles de integración importantes:

• Este endpoint devuelve un arreglo, no un objeto único.
• Los ejemplos públicos muestran CREATED después de la creación y SUBMITTED después de completar el formulario. La especificación pública no publica un enum completo, así que tu cliente debe manejar de forma segura estados desconocidos.

4. Retomar el flujo normal de BGC después del envío

La captura de datos del usuario se completa a través del formulario alojado en el Dashboard de Emptor o por teléfono con Emptor Sol.

Una vez que el precandidato haya sido enviado, continúa con los endpoints estándar de personas y reportes usando el mismo person_id que recibiste al momento de la creación.

Verifica el estado de la persona:

export COUNTRY_CODE="PE"

curl --request GET \
  --url "$BASE_URL/$COUNTRY_CODE/persons/$PERSON_ID/status" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

Obtén el estado actual de los reportes:

curl --request GET \
  --url "$BASE_URL/$COUNTRY_CODE/reports/$PERSON_ID" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

Eso te permite mantener el mismo manejo downstream que ya usas para personas BGC regulares.

Patrón de integración recomendado

• Crea el precandidato tan pronto como conozcas los datos de contacto del candidato.
• Persiste ambos IDs y el form_url.
• Consulta el esquema si quieres mostrar o validar los campos obligatorios en tu propia UI.
• Envía al candidato a form_url.
• Haz polling de GET /precandidate/{person_id} hasta que el registro sea enviado.
• Cambia a los endpoints normales de estado de persona y reportes para el resto del ciclo de vida.

Errores comunes

• 404 Pipeline not found: el pipeline_id o pipeline_name enviado no existe para tu cuenta.
• 404 Precandidate form not found: la combinación de person_id y form_id no coincide con un formulario alojado existente.

Endpoints relacionados

• Crear un precandidato
• Obtener precandidatos por person ID
• Obtener el esquema del formulario del precandidato