Get Candidate Status

GET /candidate-requests/{uuid}

This endpoint monitors the overall progress of the request and checks the individual status of each process. It returns the Request Summary by default. It is the main resource for polling flows or manual queries.

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.

---

Request Example

cURL

curl -X GET "{BASE_URL}/candidate-requests/8b9cad0e-1f20-4192-bff0-e1e043cea4db"

Node.js

const response = await fetch(
  "{BASE_URL}/candidate-requests/8b9cad0e-1f20-4192-bff0-e1e043cea4db",
  { method: "GET" },
);

API Responses

200 OK

Below is an example of the response structure. The processes object contains the list of executed validations, their start/end dates and the preliminary result.

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "El registro del candidato con National Id SEVG920929HMNRLB01 fue satisfactorio",
    "data": {
        "isCandidateRegistered": true,
        "status": "Completed",
        "candidateId": "9bNONK0yqXYlbE8iBKZZ",
        "result": "Pendiente",
        "globalEndDate": null,
        "processes": [
            {
                "id": "0ggAQfM4NIFbShqLUxxF",
                "processName": "Peps",
                "result": "Riesgo Bajo",
                "status": "Finalizado",
                "startDate": 1758651740402,
                "endDate": 1758651743232
            },
            {
                "id": "0qUJmH8GRE4JCnmDFiy9",
                "processName": "Listas negras del SAT",
                "result": "Riesgo Bajo",
                "status": "Finalizado",
                "startDate": 1758651733591,
                "endDate": 1758651741203
            },
            {
                "id": "2Gk9ezpE2gAQEekFLCTO",
                "processName": "Referencias Personales",
                "result": "Pendiente",
                "status": "Con dependencia",
                "startDate": null,
                "endDate": null
            },
            {
                "id": "45hMSTayZYZGeUTgUp2A",
                "processName": "Validación de estudios",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651735562,
                "endDate": null
            },
            {
                "id": "4uHSRL06tV2tErX8zwcx",
                "processName": "BGC Laboral",
                "result": "No disponible",
                "status": "Finalizado",
                "startDate": 1758651734432,
                "endDate": 1758825295653
            },
            {
                "id": "698BbILPWd6I0oBGZOgk",
                "processName": "Global Watch List",
                "result": "Aprobado",
                "status": "Finalizado",
                "startDate": 1758651729370,
                "endDate": 1758651737631
            },
            {
                "id": "7PQeIGuOJTUug6EISyYq",
                "processName": "Referencias Laborales",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651737626,
                "endDate": null
            },
            {
                "id": "A4mD4mGSe5Vn7ybXiHaC",
                "processName": "Geolocalización",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651734070,
                "endDate": null
            },
            {
                "id": "BGRgx6JHpDAFDszrQUGQ",
                "processName": "Documentos",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651735668,
                "endDate": null
            },
            {
                "id": "UZTVM67AaDcqVmPGKhdq",
                "processName": "BGC News",
                "result": "Aprobado",
                "status": "Finalizado",
                "startDate": 1758651741571,
                "endDate": 1758651805644
            },
            {
                "id": "jbJ6ryPsJKqt60mA2bon",
                "processName": "Reporte de Crédito",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651734729,
                "endDate": null
            },
            {
                "id": "kHQ71upc7krtkM21har2",
                "processName": "BGC Legal",
                "result": "Aprobado",
                "status": "Finalizado",
                "startDate": 1758651740531,
                "endDate": 1758651747070
            }
        ]
    }
}

200 OK (Not Found)

Below is an example of the response when the queried ID is not found

{
	"isSuccess": true,
	"statusCode": 404,
	"message": "candidate request not found",
	"data": {}
}