Bulk Register Candidates

POST /bulk-loading/upload

This endpoint registers candidates in bulk by attaching a CSV file with any number of candidates.

Query Parameters

Name	Type	Required	Value / Example
registerType	string	Yes	Method used to register new candidates. Options: byName, byNationalId

---

File

Parameter	Type	Required	Value / Example
file	Form Data	Yes	CSV file with a maximum size of 5MB

---

CSV File Template

The file must be a .csv with a header row followed by one row per candidate. The template depends on the value of registerType.

Headers must match exactly

Use the column names exactly as shown below, respecting upper/lower case and underscores (for example clientId, country_id, package_id, lastname). A column with a different name is treated as missing. We recommend including all the template columns, even when empty. Empty rows are ignored.

registerType=byNationalId

Registers the candidate from their official ID.

clientId,country_id,national_id,package_id,email,btrustProfile,btrustCategories,rfc,nss,personalReferences
cl_123456,MX,MARD020406MDFSMNA8,pkg_789012,maria.rodriguez@example.com,,,,,
cl_123456,MX,GOLJ850315HJCNPN04,pkg_789012,juan.gonzalez@example.com,,,GOLJ850315AB1,12345678901,3

Column	Required	Description
clientId	Yes	Your client identifier in Blacktrust.
country_id	Yes	Candidate's country, in ISO Alpha-2 or Alpha-3 (MX or MEX). See Supported Countries.
national_id	Yes	Official ID. It must match the country's format (in Mexico, the 18-character CURP).
package_id	Yes	Identifier of the package of Processes to run.
email	Conditional	Required if the package requires the candidate to have a user.
btrustProfile	Conditional	Required if the package includes BTrust. See package-dependent columns.
btrustCategories	Conditional	Required if btrustProfile is personalizado.
rfc	Conditional	Required if the package includes SAT Lists.
nss	No	Social Security Number (11 digits).
personalReferences	Conditional	Required if the package includes Personal References.

registerType=byName

Registers the candidate from their name and personal data.

clientId,country_id,email,name,lastname,secondlastname,sex,birthDate,state,package_id,btrustProfile,btrustCategories,rfc,nss,personalReferences
cl_123456,MX,maria.rodriguez@example.com,María,Rodríguez,Díaz,M,06/04/2002,DF,pkg_789012,,,,,
cl_123456,MX,juan.gonzalez@example.com,Juan,González,,H,15/03/1985,JC,pkg_789012,,,GOLJ850315AB1,12345678901,3

Column	Required	Description
clientId	Yes	Your client identifier in Blacktrust.
country_id	Yes	Candidate's country, in ISO Alpha-2 or Alpha-3 (MX or MEX). See Supported Countries.
email	Conditional	Required if the package requires the candidate to have a user.
name	Yes	Candidate's first name(s).
lastname	Yes	Paternal last name.
secondlastname	Yes*	Maternal last name. The column must exist, but the value may be empty if the candidate has no second last name.
sex	Yes	H (male) or M (female).
birthDate	Yes	Date of birth in DD/MM/YYYY format.
state	Yes	2-letter state code. See State Codes.
package_id	Yes	Identifier of the package of Processes to run.
btrustProfile	Conditional	Required if the package includes BTrust. See package-dependent columns.
btrustCategories	Conditional	Required if btrustProfile is personalizado.
rfc	Conditional	Required if the package includes SAT Lists.
nss	No	Social Security Number (11 digits).
personalReferences	Conditional	Required if the package includes Personal References.

* Always include the secondlastname header; leave the cell empty when it does not apply.

Package-dependent columns

Columns marked Conditional depend on the Processes included in your package. Leave them empty when they do not apply.

Column	Detail
btrustProfile	BTrust profile to apply. Use personalizado to pick specific categories.
btrustCategories	BTrust categories in a single column, comma-separated (cat1,cat2).
personalReferences	Number of references to request (greater than 0).

There are also columns that are not part of the base template and that you should add only when they apply:

Column	When to add it	Description
telephone	Optional.	Candidate's phone number.
birthDate	Optional in byNationalId.	Date of birth in DD/MM/YYYY format.
costCenter	Only if your client has cost centers enabled (then it is mandatory).	Identifier of a cost center visible to your client.
calculateRfc	Packages with the RFC validation process.	true to calculate the RFC from the name and date of birth, false to send it in rfc.
fiscalPostalCode	Packages with the RFC validation process.	5-digit fiscal postal code, as text (keeps the leading zero, e.g. 06600).

General rules

• Maximum file size: 5MB.
• If any row is missing a mandatory column or value (clientId, country_id, package_id and those specific to each registerType), the whole file is rejected with 400 and no candidate is registered.
• Format and business validations (date, sex, state, national_id, email, rfc, etc.) are applied per candidate after the upload. Those that fail are reported in the error file available when you query the upload status.
• Natural-person files must not include the legalName, companyType or incorporationDate columns: if present, the file is rejected.

---

API Responses

201 OK

Below is an example of the response structure.

{
	"isSuccess": true,
	"statusCode": 201,
	"message": "Success",
	"data": {
		"uuid": "7203d1d6-53ea-4837-8c9a-6690f0c9d07e",
		"message": "File uploaded successfully"
	}
}

UUID in Response

The UUID received in the response can later be used to check the status of the uploaded file and of each candidate it contained.