Inscribir Candidatos

POST /candidate-requests

Este endpoint inicia el flujo asíncrono para ejecutar los Processes contenidos en un packageId asignado a tu entidad.

---

Encabezados Requeridos (HTTP Headers)

Header	Tipo	Requerido	Valor / Ejemplo
Content-Type	string	Sí	application/json

Autenticación

Autentícate con el método que Blacktrust definió para tu integración: el header x-api-key o Authorization: Bearer {accessToken} (uno u otro, nunca ambos). Consulta Autenticación para saber cuál aplica en tu caso.

---

Ejemplos de Body de Registro

Selecciona la variante de registro que deseas implementar para ver la estructura exacta del JSON:

Registro por national ID

El método más eficiente. Al activar byNationalId: true, el motor de BlackTrust extraerá y validará automáticamente el nombre completo, fecha de nacimiento, sexo y estado de origen directamente de la registraduría oficial. No es necesario enviar los datos demográficos individuales.

{
  "clientId": "CL_12345",
  "package": "PKG_MX_PRO_02",
  "country": "MX",
  "byNationalId": true,
  "nationalId": "MARD020406MDFSMNA8",
  "taxClassification": "PF"
}

Registro por nombre

{
  "byNationalId": false,
  "clientId": "CL_12345",
  "name": "Jane",
  "lastName": "Doe",
  "secondLastName": "",
  "birthDate": "xxxxxxxxxxxxxx",
  "sex": "xxxxxxxxxxxxxx",
  "state": "xxxxxxxxxxxxxx",
  "package": "xxxxxxxxxxxxxx",
  "rfc": "xxxxxxxxxxxxxx",
  "consent": {
    "consentDate": "30/12/2024 03:30:15",
    "termsAgreementDate": "30/12/2024 03:30:15",
    "consentNIP": "1996"
  },
  "homeAddress": {
    "streetAndNumber": "xxxxxxxxxxxxxx",
    "delegationOrMunicipality": "xxxxxxxxxxxxxx",
    "postalCode": "xxxxx",
    "city": "xxxxxxxxxxxxxx",
    "state": "xx"
  }
}

Registro Internacional (Ej. PA)

{
  "clientId": "CL_12345",
  "package": "PKG_INT_BASIC",
  "country": "PA",
  "name": "JANE",
  "lastName": "DOE",
  "birthDate": "1994-03-22",
  "sex": "F"
}

Relación de propiedades

Parámetro	Tipo	Requerido	Descripción
byNationalId	boolean	Sí	Indica si el registro se realiza mediante identificador oficial.
package	string	Sí	ID del paquete de validaciones a ejecutar.
taxClassification	string	Sí	Clasificación fiscal del candidato (PF o PM).
clientId	string	Sí	Identificador del cliente asignado por BlackTrust.
businessName	string	Condicional	Razón social. Requerido únicamente si taxClassification es PM.
nationalId	string	Condicional	Documento de identidad oficial. Requerido únicamente si byNationalId es true.
name	string	Condicional	Nombre(s) del candidato. Requerido únicamente si byNationalId es false.
lastName	string	Condicional	Primer apellido del candidato. Requerido únicamente si byNationalId es false.
secondLastName	string	No	Segundo apellido del candidato.
birthDate	string	Condicional	Fecha de nacimiento en formato DD/MM/YYYY. Requerido únicamente si byNationalId es false.
sex	string	Condicional	Género del candidato (H, M u X). Requerido únicamente si byNationalId es false.
state	string	Condicional	Clave de estado de 2 letras (ej. JC). Requerido únicamente si byNationalId es false. consultar estados soportados.
country	string	No	Código ISO a 3 letras de país. Defecto: MEX. consultar todos los países soportados.
registrationCountry	string	Condicional	Código de país de registro comercial Catálogo wc-countries. Requerido únicamente si el paquete a registrar contiene el proceso World Check
regime	string	Condicional	Régimen fiscal. Requerido únicamente en PM. Catálogo de régimens fiscales
requestId	string	No	Identificador único de la solicitud.
rfc	string	Condicional	Registro Federal de Contribuyentes. Requerido únicamente en procesos de crédito.
nss	string	No	Número de Seguridad Social (11 dígitos numéricos).
email	string	Condicional	Correo electrónico del candidato. Requerido únicamente si el paquete requiere interacción con el candidato
telephone	string	No	Número telefónico de contacto.
consent	object	Condicional	Objeto con las fechas e identificador de consentimiento para el paquete de crédito.
consent.consentDate	string	Sí (en consent)	Fecha de aceptación del consentimiento (dd/MM/yyyy HH:mm:ss).
consent.termsAgreementDate	string	Sí (en consent)	Fecha de aceptación de términos (dd/MM/yyyy HH:mm:ss).
consent.consentNIP	string	Sí (en consent)	NIP de autorización (dígitos 3-4 deben coincidir con año del RFC).
homeAddress	object	No	Objeto con los datos de la dirección de residencia del candidato.
homeAddress.streetAndNumber	string	Sí (en homeAddress)	Calle y número (1 a 70 caracteres alfanuméricos).
homeAddress.delegationOrMunicipality	string	Sí (en homeAddress)	Alcaldía o municipio (1 a 70 caracteres alfanuméricos).
homeAddress.postalCode	string	Sí (en homeAddress)	Código postal (exactamente 5 dígitos numéricos).
homeAddress.city	string	Sí (en homeAddress)	Ciudad (1 a 70 caracteres alfanuméricos).
homeAddress.state	string	Sí (en homeAddress)	Estado o entidad federativa.
hasWorkExperience	boolean	No	Bandera que indica si el candidato tiene o no experiencia laboral.
workAddress	object	No	Objeto con la dirección laboral. Requerido si hasWorkExperience es true.
workAddress.company	string	Sí (en workAddress)	Nombre de la empresa (1 a 70 caracteres alfanuméricos).
profileId	string	No	Identificador del perfil asignado.
profile	string	No	Nombre del perfil.
costCenter	number	Condicional	Centro de costos para facturación o control interno. Requerido si el cliente tiene la modalidad de centro de costos activa.
gender	string	Condicional	Género del candidato (H, M o X). Requerido únicamente si el paquete tiene pruebas psicométricas

Reglas de Validación de Negocio

Nuestras reglas de entrada procesan y validan los datos previa ejecución asíncrona. Se retornará un error 400 Bad Request o 422 Unprocessable Entity si no se cumplen las siguientes reglas:

Validaciones Demográficas y Formatos de Registro (Personas Físicas - PF)

Identificación Oficial (nationalId): Si byNationalId es true, el identificador debe cumplir con el patrón oficial del país especificado:

MEX / DEFAULT: 18 caracteres de la clave CURP.

DOM: 11 dígitos numéricos.

GTM / HND: 13 dígitos numéricos.

JAM: 9 dígitos numéricos.

PAN: Expresión regular de cédula panameña.

consultar todos los países soportados

Formato de Fecha de Nacimiento (birthDate): Debe seguir estrictamente el formato DD/MM/YYYY y encontrarse entre el 01/01/1900 y la fecha actual.

Mayoría de Edad: El candidato debe tener 18 años cumplidos al momento del registro (calculado mediante la propiedad birthDate).

Estados (state): La clave de entidad federativa debe ser un código oficial de 2 letras (ej. JC, DF, NL, SP). consultar estados soportados

Género (sex): Únicamente se aceptan los valores H (Hombre), M (Mujer) u X (No binario).

Registro Corporativo (Personas Morales - PM)

Campos Obligatorios: Requiere obligatoriamente los parámetros businessName y regime.

El parámetro regime debe existir dentro del catálogo corporativo del sistema.

Si se proporciona registrationCountry, este debe coincidir con un código de país válido en el catálogo (wc-countries).

Módulo de Crédito y Consenso (Buró de Crédito)

Si el paquete contratado incluye procesos de consulta crediticia:

RFC Obligatorio: El parámetro rfc es requerido.

Validación PIN/NIP (consentNIP): Los dígitos en las posiciones 3 y 4 del consentNIP deben coincidir exactamente con el año de nacimiento extraído del RFC (caracteres 5 y 6 del RFC).

Direcciones Requeridas (homeAddress / workAddress): Se exige la estructura completa de homeAddress. En caso de indicar experiencia laboral previa (hasWorkExperience: true), se exigirá también el envío del objeto workAddress.

Validación de Cliente, Paquete y Reglas de Registro

Existencia Activa: El API verifica que el clientId y el package existan y estén asignados activamente.

Modos de Registro Habilitados: El paquete contratado determina si se permite el registro por identificador oficial (byNationalId: true) o el registro demográfico tradicional (byNationalId: false).

Coincidencia RFC vs CURP: Si se proporciona tanto el rfc como la CURP (nationalId), los primeros 10 caracteres de ambos identificadores deben coincidir exactamente.