Register Candidates

POST /candidate-requests

This endpoint starts the asynchronous flow that runs the Processes contained in a packageId assigned to your entity.

Required Headers (HTTP Headers)

Header	Type	Required	Value / Example
`Content-Type`	`string`	Yes	`application/json`

Authentication

Authenticate with the method Blacktrust defined for your integration: the x-api-key header or Authorization: Bearer {accessToken} (one or the other, never both). See Authentication to find out which one applies to you.

Registration Body Examples

Select the registration variant you want to implement to see the exact JSON structure:

Registration by national ID
Registration by name
International Registration (e.g. PA)

The most efficient method. When byNationalId: true is set, the BlackTrust engine automatically extracts and validates the full name, date of birth, sex and state of origin directly from the official registry. There is no need to send the individual demographic data.

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

{
  "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"
  }
}

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

Property Reference

Parameter	Type	Required	Description
`byNationalId`	`boolean`	Yes	Indicates whether registration is done using an official identifier.
`package`	`string`	Yes	ID of the validation package to run.
`taxClassification`	`string`	Yes	Tax classification of the candidate (`PF` or `PM`).
`clientId`	`string`	Yes	Client identifier assigned by BlackTrust.
`businessName`	`string`	Conditional	Business name. Required only if `taxClassification` is `PM`.
`nationalId`	`string`	Conditional	Official identity document. Required only if `byNationalId` is `true`.
`name`	`string`	Conditional	Candidate's first name(s). Required only if `byNationalId` is `false`.
`lastName`	`string`	Conditional	Candidate's first last name. Required only if `byNationalId` is `false`.
`secondLastName`	`string`	No	Candidate's second last name.
`birthDate`	`string`	Conditional	Date of birth in `DD/MM/YYYY` format. Required only if `byNationalId` is `false`.
`sex`	`string`	Conditional	Candidate's sex (`H`, `M` or `X`). Required only if `byNationalId` is `false`.
`state`	`string`	Conditional	2-letter state code (e.g. `JC`). Required only if `byNationalId` is `false`. see supported states.
`country`	`string`	No	3-letter ISO country code. Default: `MEX`. see all supported countries.
`registrationCountry`	`string`	Conditional	Business registration country code, `wc-countries` Catalog. Required only if the package to register contains the World Check process
`regime`	`string`	Conditional	Tax regime. Required only for `PM`. Tax regimes Catalog
`requestId`	`string`	No	Unique identifier of the request.
`rfc`	`string`	Conditional	Registro Federal de Contribuyentes. Required only for credit Processes.
`nss`	`string`	No	Social Security Number (11 numeric digits).
`email`	`string`	Conditional	Candidate's email address. Required only if the package requires interaction with the candidate
`telephone`	`string`	No	Contact phone number.
`consent`	`object`	Conditional	Object with the consent dates and identifier for the credit package.
`consent.consentDate`	`string`	Yes (in consent)	Consent acceptance date (`dd/MM/yyyy HH:mm:ss`).
`consent.termsAgreementDate`	`string`	Yes (in consent)	Terms acceptance date (`dd/MM/yyyy HH:mm:ss`).
`consent.consentNIP`	`string`	Yes (in consent)	Authorization PIN (digits 3-4 must match the RFC year).
`homeAddress`	`object`	No	Object with the candidate's home address data.
`homeAddress.streetAndNumber`	`string`	Yes (in homeAddress)	Street and number (1 to 70 alphanumeric characters).
`homeAddress.delegationOrMunicipality`	`string`	Yes (in homeAddress)	Borough or municipality (1 to 70 alphanumeric characters).
`homeAddress.postalCode`	`string`	Yes (in homeAddress)	Postal code (exactly 5 numeric digits).
`homeAddress.city`	`string`	Yes (in homeAddress)	City (1 to 70 alphanumeric characters).
`homeAddress.state`	`string`	Yes (in homeAddress)	State or federal entity.
`hasWorkExperience`	`boolean`	No	Flag indicating whether the candidate has work experience.
`workAddress`	`object`	No	Object with the work address. Required if `hasWorkExperience` is `true`.
`workAddress.company`	`string`	Yes (in workAddress)	Company name (1 to 70 alphanumeric characters).
`profileId`	`string`	No	Identifier of the assigned profile.
`profile`	`string`	No	Profile name.
`costCenter`	`number`	Conditional	Cost center for billing or internal control. Required if the client has the cost center mode enabled.
`gender`	`string`	Conditional	Candidate's gender (`H`, `M` or `X`). Required only if the package includes psychometric tests

Business Validation Rules

Our input rules process and validate the data before asynchronous execution. A 400 Bad Request or 422 Unprocessable Entity error is returned if the following rules are not met:

Demographic Validations and Registration Formats (Individuals - PF)

Official Identification (nationalId): If byNationalId is true, the identifier must match the official pattern of the specified country:

MEX / DEFAULT: 18-character CURP key.

DOM: 11 numeric digits.

GTM / HND: 13 numeric digits.

JAM: 9 numeric digits.

PAN: Panamanian cédula regular expression.

see all supported countries

Date of Birth Format (birthDate): Must strictly follow the DD/MM/YYYY format and be between 01/01/1900 and the current date.

Legal Age: The candidate must be at least 18 years old at the time of registration (calculated from the birthDate property).

States (state): The state code must be an official 2-letter code (e.g. JC, DF, NL, SP). see supported states

Sex (sex): Only the values H (Male), M (Female) or X (Non-binary) are accepted.

Corporate Registration (Legal Entities - PM)

Required Fields: The businessName and regime parameters are mandatory.

The regime parameter must exist in the system corporate catalog.

If registrationCountry is provided, it must match a valid country code in the catalog (wc-countries).

Credit and Consent Module (Credit Bureau)

If the contracted package includes credit check Processes:

RFC Required: The rfc parameter is required.

PIN Validation (consentNIP): The digits at positions 3 and 4 of consentNIP must exactly match the birth year extracted from the RFC (characters 5 and 6 of the RFC).

Required Addresses (homeAddress / workAddress): The complete homeAddress structure is required. If prior work experience is indicated (hasWorkExperience: true), the workAddress object must also be sent.

Client, Package and Registration Rules Validation

Active Existence: The API verifies that the clientId and package exist and are actively assigned.

Enabled Registration Modes: The contracted package determines whether registration by official identifier (byNationalId: true) or traditional demographic registration (byNationalId: false) is allowed.

RFC vs CURP Match: If both the rfc and the CURP (nationalId) are provided, the first 10 characters of both identifiers must match exactly.

Required Headers (HTTP Headers)​

Registration Body Examples​

Property Reference​

Business Validation Rules​

Required Headers (HTTP Headers)

Registration Body Examples

Property Reference

Business Validation Rules