Skip to main content

Credit Report (Credit Bureau)

The Credit Report process automatically evaluates a candidate's credit history and financial risk score.

This service is built on a flexible, modular architecture, making it easy to adapt to each client's compliance and conversion needs.

To run the Credit Bureau query, the candidate's legal authorization is required. The client must contractually choose one of the following two operating schemes to collect that authorization:

Option A: Collection by Blacktrust (btapp Platform)​

  • When it applies: When apiConsentRequired is set to false commercially.
  • Developer flow: The client registers the candidate through the API sending only the basic demographic data (without the consent object).
  • Candidate experience: Blacktrust automatically sends the candidate an invitation email. The candidate signs in or creates an account on the btapp platform, reviews the terms and conditions contract, and accepts the digital consent by entering their date of birth as a signature.

Option B: Collection by the Client (Signature via API)​

  • When it applies: When apiConsentRequired is set to true commercially.
  • Developer flow: The client assumes legal responsibility for collecting the candidate's authorization and addresses within their own system or application. When registering the candidate through the Blacktrust API, the structured nodes consent, homeAddress, workAddress must be sent.
  • Candidate experience: The flow is much faster. An invitation email is no longer sent automatically to the candidate.

1. Configuration Modes (Commercial Flow)​

This process is highly configurable and is set up at the contract level with the Blacktrust commercial team through 4 key flags. Depending on which flags are enabled, the candidate experience and the level of detail in the result vary as follows:

Contract-Level Configuration

The following flags control the consent flow and the granularity of the information returned by the API:

FlagTypeDescriptionBehavior when trueBehavior when false
apiConsentRequiredBooleanControls the origin of the consent signature.The consent object is strictly required in the registration payload.The candidate signs digitally by manually accessing the btapp platform.
creditReportPdfBooleanEnables export of the bureau's official PDF.The API response includes the creditReportFile field with the temporary PDF URL.The official PDF download link is omitted.
creditScoreBooleanAdds the simplified bureau score.Adds the bcScore object with the unified score and the standardized rating.The bcScore block is excluded from the process results.
fullCreditDataBooleanIncludes granular credit information.The full buroInformation node is included (accounts, historical addresses, etc.).Detailed account credit information is omitted.

2. Registration Guide (Input Payload)​

To start a candidate's credit bureau query, send a request to the registration endpoint. The following example payload highlights two advanced integration capabilities:

When your contract configuration requires consent via API, you must attach the consent node. This certifies that the candidate authorized the query from your own application.

Important Development Note

The consentNIP field must be strictly the 4 digits of the candidate's birth year (e.g., '1985'), physically verified against their official identity document.

B) Address Pre-filling (Optional)​

You can send the homeAddress (home address) and workAddress (work address) objects directly in the registration. If your API sends this structured data, the candidate skips this step in the platform form, which significantly increases the conversion rate and speeds up the recruiting flow.

Example Payload (POST /candidate-requests)​

{
  "byNationalId": true,
  "nationalId": "xxxxxxxxxxxxxx",
  "clientId": "xxxxxxxxxxxxxx",
  "package": "xxxxxxxxxxxxxx",
  "taxClassification": "xxxxxxxxxxxxxx",
  "rfc": "xxxxxxxxxxxxxx",
  // [Required only if apiConsentRequired = true]
  "consent": {
    "consentNIP": "1985",
    "consentAccepted": true,
    "consentDate": "2026-06-17T09:38:18Z"
  },
  // [Opcional]
  "homeAddress": {
    "street": "Avenida Insurgentes Sur",
    "externalNumber": "1234",
    "internalNumber": "5B",
    "neighborhood": "Del Valle",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zipCode": "03100",
    "country": "MX"
  },
  // [Opcional]
  "workAddress": {
    "street": "Paseo de la Reforma",
    "externalNumber": "505",
    "internalNumber": "Piso 12",
    "neighborhood": "Cuauhtémoc",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zipCode": "06500",
    "country": "MX"
  }
}

3. Dynamic Response Structure​

The process response adapts dynamically to your commercial contract configuration. The response formats for each contracted feature set are shown below:

Full Process Detail​

This view is returned when querying the process detail while all extended-information flags (fullCreditData, creditScore, and creditReportPdf) are active.

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "Success",
    "data": {
        "processId": "jbJ6ryPsJKqt60mA2bon",
        "processName": "Reporte de Crédito",
        "detail": {
            "candidateFinished": true, // Indicates whether the candidate has completed all actions required in their flow
            "consentAccepted": true,    // Confirms a valid legal signature exists (via API or platform)
            "creditConsultationDate": "10012025",
            
            // [Enabled only if fullCreditData = true contractually]
            "buroInformation": {
                "encabezado": { ... },
                "nombre": {
                    "apellidoPaterno": "GARCIA",
                    "apellidoMaterno": "RODRIGUEZ",
                    "primerNombre": "JUAN",
                    "fechaNacimiento": "15081985",
                    "rfc": "GARJ850815XX1", // Official Mexican format
                    "nacionalidad": "MX",
                    "estadoCivil": "S",
                    "sexo": "M"
                },
                "domicilios": [ 
                    // History of tax and residential addresses reported to the operator
                ],
                "cuentas": [ 
                    // Payment behavior of active and closed credits (R/CC mechanism)
                ],
                "resumenReporte": [ ... ],
                "scoreBuroCredito": [ ... ]
            },
            
            // [Enabled only if creditScore = true]
            "bcScore": [
                {
                    "nombreScore": "BC SCORE",
                    "codigoScore": "002",
                    "valorScore": "0680",
                    "score": "85.00", // Blacktrust standardized rating
                    "razon": [
                        "Antigüedad de la cuenta más antigua.",
                        "Nivel de endeudamiento."
                    ]
                }
            ],
            
            // [Enabled only if creditReportPdf = true]
            "creditReportFile": "https://storage.googleapis.com/btapp-bucket/reportes/ejemplo-anonimo.pdf?token=abc123token"
        },
        "allowClientView": true,
        "status": "Finalizado",
        "result": "Proceso completo"
    }
}