Cadastro Único Database Verification

  • Updated on Dec 16, 2025
  • Published on Dec 15, 2025
Prev Next

Available via API

Available via SDK

Needs configuration on Veriff's side

Needs a separate integration

Needs a separate webhook

✅

❌

✅

✅

❌

Cadastro Único Database Verification is a solution that validates Brazilian users against social benefit registries to determine if they receive government assistance. This solution queries Brazil's unified registry for social programs to check enrollment status in various government benefit programs including Bolsa Família, BCP (Continuous Cash Benefit), Seguro Defeso (Artisanal Fishermen Insurance), and Emergency Aid (Auxílio Emergencial). This solution’s key benefits include regulatory compliance for Brazilian financial services and gambling operators, fraud prevention through cross-referencing government records, and real-time validation against multiple government registries.

Cadastro Único Database Verification is available via API only. The solution can be:

  • an add-on to your document + selfie IDV or document-only IDV, or

  • used separately as a standalone check

All the session data is provided via API or in the the Veriff Customer Portal. All session-related info is returned via decision webhook and can be polled from different API endpoints. The results of the verification can also be viewed in the Veriff Customer Portal, on the Session → Webhooks tab.

If any data was extracted from the document, this data is provided in the decision webhook payload and GET /decision endpoint’s response payload.

Contact your solutions engineer for info and configuration.

Prerequisites

  • You have an integration set up with Veriff

  • The feature is configured for that integration by your Solutions Engineer

  • You have configured the decision webhook to get responses from Veriff (see the how-to in webhooks’ Set up webhooks section)

  • Ensure that  you are ready to collect and send Veriff your end-user’s data (CPF number and date of birth)

  • Because the solution is available only via API:

    • Veriff strongly recommends you collect and send additional device/session data for improved fraud mitigation

    • Veriff strongly recommends that you create and send us the endUserId or vendorData

Key terminology

Term

Description

CPF number

Cadastro de Pessoas Físicas, Brazilian individual taxpayer registry 11-digit number

Cadastro Único

Brazil's unified registry for social programs

Bolsa Família

Family assistance program

BCP

Benefício de Prestação Continuada, continuous cash benefit for elderly and disabled

Seguro Defeso

Artisanal fishermen insurance

Auxílio Emergencial

Emergency aid program (COVID-19 related)

NIS

Social Identification Number

Quadro Social e Administrativo

Register of partners and administrators of a company

IBGE, Instituto Brasileiro de Geografia e Estatística

Brazilian Institute of Geography and Statistics, grants 7-digit numeric codes to Brazilian states

End-user data sources

The “end-user data sources” refer to different origins from which the end-user’s information can be collected for database verification. There are two data sources: document data and initData.

Document data

This is data that is extracted from the end-user’s document. Includes information extracted from Brazilian identity documents (driver's licenses, ID cards).

If using document extraction flow, the CPF number and date of birth are extracted from Brazilian documents and passed automatically to the Cadastro Único Database Verification flow.

InitData

This is data that you provide when creating a verification session, i.e. the parameters you specify in the POST /sessions request. Includes information like names, date of birth, address, phone number, ID number, gender etc.

InitData takes precedence over document extraction if both are present.

Parameters that can be sent via initData:

  • CPF number via verification.person.idNumber

  • Date of birth via verification.person.dateOfBirth

Flow overview

Use via API

Standalone Cadastro Único Database Verification verification

Use when you only need to verify Cadastro Único Database Verification without collecting document images.

  1. Generate a verification session using the API keys and the baseURL of your Cadastro Único Database Verification integration (see the API Documentation and API Reference[↗] how to find these)

    1. Make sure to pass the mandatory verification.person.idNumber and verification.person.dateOfBirth parameters with the end-user's CPF and date of birth values

    2. Veriff strongly recommends you create and send the endUserId or vendorData

    3. Veriff strongly recommends you collect and send additional session/device data via POST sessions/{sessionid}/collected-data[↗] for improved fraud detection

Session creation bash example

curl -X POST \
  --url 'https://example.veriff.com/v1/sessions/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -d '{
    "verification": {
      "callback": "https://example.com/webhook",
      "person": {
        "idNumber": "12345678901",
        "dateOfBirth": "1990-01-15"
      }
    
 }
  }'

Session creation json example

{
  "verification": {
    "callback": "https://example.com/webhook",
    "person": {
      "idNumber": "12345678901",
      "dateOfBirth": "1990-01-15"
    }
  }
}

  1. Patch session status to submitted status via PATCH /sessions/{sessionId}[↗]

Session update bash example

curl -X PATCH \
  --url 'https://example.veriff.com/v1/sessions/{sessionId}' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "status": "submitted"
  }'

Session update json example

{
  "status": "submitted"
}

  1. Check the decision data and/or session related info from the decision webhook payload (see an example below) and/or query the data from the GET /sessions/{sessionId}/decision endpoint (see an example below). Solution-specific overview of what to expect is provided below in Solution-specific parameters section.

Cadastro Único Database Verification with document verification

  1. Generate a verification session using the API keys and the baseURL of your Cadastro Único Database Verification integration (see the API Documentation and API Reference[↗] how to find these)

    1. Make sure to pass the mandatory verification.person.idNumber and verification.person.dateOfBirth parameters if not relying on document extraction

    2. Veriff strongly recommends you create and send the endUserId or vendorData

    3. Veriff strongly recommends you collect and send additional session/device data via POST sessions/{sessionid}/collected-data[↗] for improved fraud detection

Session creation bash example

curl -X POST \
  --url 'https://example.veriff.com/v1/sessions/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -d '{
    "verification": {
      "callback": "https://example.com/webhook",
      "person": {
        "idNumber": "12345678901",
        "dateOfBirth": "1990-01-15"
      }
    }
  }'

Session creation json example

{
  "verification": {
    "callback": "https://example.com/webhook",
    "person": {
      "idNumber": "12345678901",
      "dateOfBirth": "1990-01-15"
    }
  }
}

  1. Use your image-capturing method, or prepare previously collected document image(s)

  2. Upload the end-user's media via POST /sessions/{sessionId}/media call

    1. Specify the image.context as appropriate for the image context types (e.g., document-front and face or face-pre) (see Context types (image, video) for more info about image context types)

Media upload bash example

curl -X POST \
  --url 'https://example.veriff.com/v1/sessions/{sessionId}/media' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "image": {
      "data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...",
      "context": "document-front"
    }
  }'

Media upload json example

{
  "image": {
    "data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...",
    "context": "document-front"
  }
}

  1. Patch session status to submitted status via PATCH /sessions/{sessionId}[↗]

Session update bash example

curl -X PATCH \
  --url 'https://example.veriff.com/v1/sessions/{sessionId}' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "status": "submitted"
  }'

Session update json example

{
  "status": "submitted"
}

  1. Check the decision data and/or session related info from the decision webhook payload (see an example below) and/or query the data from the GET /sessions/{sessionId}/decision endpoint (see an example below). Solution-specific overview of what to expect is provided below in Solution-specific parameters section.

Find decision and/or session related info

You can get the data from three sources:

  • Receive the decision webhook (example below)

  • Query the results via GET /sessions/{sessionId}/decision (example below)

  • View the session in Veriff Customer Portal

Note that the decision webhook and GET /sessions/{sessionId}/decision payloads are identical.

Solution-specific parameters

Info related to Cadastro Único Database Verification is returned in additionalVerifiedData.cadastroUnico object. This object is structured into two main sections: validations and registryResponse objects.

These provide detailed information about the end-user's enrollment status in various Brazilian government benefit programs and enables you to implement business logic based on government benefit status for compliance with Brazilian regulations.

validations object

This object contains the results of various rule checks run against the user. Each key represents a specific rule. Every rule inside the validations object shares the following structure:

  • result: string Shows the outcome of the validation, usually success or failure

  • reasons: array | null A list of strings explaining why the validation failed. If result is success, this is usually null or empty.

To see the full explanation of parameters inside the objects, see the webhook payload explanation section.

Parameter

Description

processing object

Indicates if the processing of the validation was successful

isUserDataValid object

Checks if the input data provided for the end-user (e.g., CPF, Name) format is valid

isNotBcpBeneficiary object

Checks if the end-user is NOT a recipient of BCP (Continuous Cash Benefit). A failure here means the end-user IS a beneficiary.

isNotBolsaFamiliaBeneficiary object

Checks if the end-user is NOT a recipient Bolsa Família. A failure here means the end-user IS a recipient.

isNotSeguroDefesoBeneficiary object

Checks if the end-user is NOT a recipient Seguro Defeso (Artisanal Fishermen Insurance). A failure here means the end-user IS a recipient.

isNotCadastroUnicoBeneficiary object

Checks if the end-user is NOT found in the general Cadastro Único registry. A failure here means the end-user was found.

isNotAuxilioEmergencialBeneficiary object

Checks if the end-user is NOT a recipient of the Emergency Aid (Auxílio Emergencial). A failure here means the end-user is a recipient.

registryResponse object

This object presents detailed data regarding specific social benefits from registries. To see the full explanation of parameters inside the objects, see the webhook payload explanation section.

Parameter

Description

bcpBenefit object

Details regarding the Benefício de Prestação Continuada (Continuous Cash Benefit), a social assistance benefit for the elderly and people with disabilities

bolsaFamiliaBenefit object

Details regarding the Bolsa Família program (formerly Auxílio Brasil)

seguroDefesoBenefit object

Details regarding the Seguro Defeso, a temporary benefit paid to professional artisanal fishermen during the period when fishing is prohibited (closed season) for species preservation

auxilioEmergencialBenefit object

Details regarding the Auxílio Emergencial (Emergency Aid), primarily distributed during the COVID-19 pandemic

Example with only solution-specific parameters

{
    "verifications": {
        "additionalVerifiedData": {
            "cadastroUnico": {
                "validations": {
                    "processing": {
                        "result": "success",
                        "reasons": null
                    },
                    "isUserDataValid": {
                        "result": "success",
                        "reasons": null
                    },
                    "isNotBcpBeneficiary": {
                        "result": "failure",
                        "reasons": [
                            "User is bcp beneficiary"
                        ]
                    },
                    "isNotBolsaFamiliaBeneficiary": {
                        "result": "success",
                        "reasons": []
                    },
                    "isNotSeguroDefesoBeneficiary": {
                        "result": "failure",
                        "reasons": [
                            "User is seguro defeso beneficiary"
                        ]
                    },
                    "isNotCadastroUnicoBeneficiary": {
                        "result": "success",
                        "reasons": []
                    },
                    "isNotAuxilioEmergencialBeneficiary": {
                        "result": "failure",
                        "reasons": [
                            "User is auxilio emergencial beneficiary"
                        ]
                    }
                },
                "registryResponse": {
                    "bcpBenefit": {
                        "state": "SP",
                        "benefitNumber": "",
                        "isInRegistry": true,
                        "beneficiaryNis": "",
                        "referenceMonth": "202210",
                        "competenceMonth": "202210",
                        "installmentValue": "1.212,00",
                        "municipalityName": "OSASCO",
                        "judiciallyGrantedBenefit": ""
                    },
                    "bolsaFamiliaBenefit": {
                        "qsa": true,
                        "currentlyActive": false,
                        "lastBenefitDate": "05/12/2022",
                        "dataInconsistency": false,
                        "firstBenefitDate": "05/12/2022",
                        "lastBenefitValue": "",
                        "last12MonthsData": "dez/25 - NAO, nov/25 - NAO, out/25 - NAO, set/25 - NAO, ago/25 - NAO, jul/25 - NAO, jun/25 - NAO, mai/25 - NAO, abr/25 - NAO, mar/25 - NAO, fev/25 - NAO, jan/25 - NAO",
                        "lastBenefitPayment": "",
                        "wasBenefitRecipient": true,
                        "currentlyInBolsaFamilia": false,
                        "employmentLinkLast5Years": true
                    },
                    "seguroDefesoBenefit": {
                        "isInRegistry": true,
                        "beneficiaryCpf": "12345678901",
                        "beneficiaryNis": "12345678901",
                        "beneficiaryName": "MARIA SILVA SANTOS",
                        "beneficiaryState": "AL",
                        "municipalityCode": "2745",
                        "municipalityName": "CORURIPE",
                        "benefitReferenceMonth": "01/10/2022",
                        "installmentValueReceived": "1212.00",
                        "fishingRegistrationNumber": "123456",
                        "bolsaFamiliaInsuranceSameDate": false
                    },
                    "auxilioEmergencialBenefit": {
                        "state": "PR",
                        "value": "300,00",
                        "observation": "NAO HA",
                        "installments": "9",
                        "municipality": "CAMBE",
                        "classification": "CADUN NAO BOLSA",
                        "isInRegistry": true,
                        "availableMonth": "12/2020",
                        "municipalityCode": "1234567"
                    }
                }
            }
        }
    }
}

If a document was used in the verification, all the info that the system is able to extract from the document is returned in verification.person and verification.document objects.

Webhook payload

Below is an example and an explanation of the decision webhook payload, showing only the mandatory parameters for a Cadastro Único Database Verification session.

Depending on your integration configuration, the payload may contain additional parameters. To find more info about those parameters, see the decision webhook documentation.

Sample request

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": null,
    "endUserId": null,
    "status": "approved",
    "code": 9001,
    "reason": null,
    "reasonCode": null,
    "decisionTime": "2025-12-10T12:00:00.000+02:00",
    "acceptanceTime": "2025-12-10T11:59:00.000+02:00",
    "submissionTime": "2025-12-10T11:59:30.000000+02:00",
    "person": {
      "firstName": "MARIA",
      "lastName": "SILVA SANTOS",
      "dateOfBirth": "1990-01-15",
      "gender": "F",
      "nationality": "BR",
      "idNumber": "12345678901",
      "yearOfBirth": "1990",
      "placeOfBirth": "BRAZIL"
    },
    "document": {
      "number": "AB123456",
      "type": "ID_CARD",
      "country": "BR",
      "state": "DF"
    },
    "additionalVerifiedData": {
      "cadastroUnico": {
        "validations": {
          "processing": {
            "result": "success",
            "reasons": null
          },
          "isUserDataValid": {
            "result": "success",
            "reasons": null
          },
          "isNotBcpBeneficiary": {
            "result": "failure",
            "reasons": ["User is bcp beneficiary"]
          },
          "isNotBolsaFamiliaBeneficiary": {
            "result": "success",
            "reasons": []
          },
          "isNotSeguroDefesoBeneficiary": {
            "result": "failure",
            "reasons": ["User is seguro defeso beneficiary"]
          },
          "isNotCadastroUnicoBeneficiary": {
            "result": "success",
            "reasons": []
          },
          "isNotAuxilioEmergencialBeneficiary": {
            "result": "failure",
            "reasons": ["User is auxilio emergencial beneficiary"]
          }
        },
        "registryResponse": {
          "bcpBenefit": {
            "state": "SP",
            "benefitNumber": "",
            "isInRegistry": true,
            "beneficiaryNis": "",
            "referenceMonth": "202210",
            "competenceMonth": "202210",
            "installmentValue": "1.212,00",
            "municipalityName": "OSASCO",
            "judiciallyGrantedBenefit": ""
          },
          "bolsaFamiliaBenefit": {
            "qsa": true,
            "currentlyActive": false,
            "lastBenefitDate": "05/12/2022",
            "dataInconsistency": false,
            "firstBenefitDate": "05/12/2022",
            "lastBenefitValue": "",
            "last12MonthsData": "dez/25 - NAO, nov/25 - NAO, out/25 - NAO",
            "lastBenefitPayment": "",
            "wasBenefitRecipient": true,
            "currentlyInBolsaFamilia": false,
            "employmentLinkLast5Years": true
          },
          "seguroDefesoBenefit": {
            "isInRegistry": true,
            "beneficiaryCpf": "12345678901",
            "beneficiaryNis": "12345678901",
            "beneficiaryName": "MARIA SILVA SANTOS",
            "beneficiaryState": "AL",
            "municipalityCode": "1234",
            "municipalityName": "CORURIPE",
            "benefitReferenceMonth": "01/10/2022",
            "installmentValueReceived": "1212.00",
            "fishingRegistrationNumber": "123456",
            "bolsaFamiliaInsuranceSameDate": false
          },
          "auxilioEmergencialBenefit": {
            "state": "PR",
            "value": "300,00",
            "observation": "NAO HA",
            "installments": "9",
            "municipality": "CAMBE",
            "classification": "CADUN NAO BOLSA",
            "isInRegistry": true,
            "availableMonth": "12/2020",
            "municipalityCode": "1234567"
          }
        }
      }
    },
    "comments": [],
    "technicalData": {
      "ip": "192.168.1.1"
    }
  }
}

Request properties explained

  • status: string Status of the response

  • verification: object Verification request decision object. null if decision is not available yet

    • id: string UUID v4 which identifies the verification session

    • attemptId: string UUID v4 of the attempt which received a status (as shown in verification.status field)

    • vendorData: string | null The unique identifier that you created for your end-user. null if not specified

    • endUserId: string | null The UUID that you created for your end-user. null if not specified

    • status: string Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

    • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104, 9121. For more info, see the verification session decision codes

    • reason: string | null Reason why the verification failed

    • reasonCode: integer | null Reason code of the failed verification. For more info, see the possible codes for a failed verification

    • decisionTime: string | null Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

    • acceptanceTime: string Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

    • submissionTime: string Timestamp of when the session was submitted, represented as UTC YYYY-MM-DDTHH:MM:SS.SSSSSS+Timezone Offset (ISO 8601)

    • person: object Data about the verified person

      • firstName: string | null Person's first name as written on the document

      • lastName: string | null Person's last name as written on the document

      • dateOfBirth: string Person's date of birth, represented as YYYY-MM-DD

      • gender: string | null Person's gender, represented as M or F, or null if not present

      • nationality: string | null Person's nationality, represented as ISO 3166 alpha-2 or alpha-3 number

      • idNumber: string | null National identification number

      • yearOfBirth: string | null Person's year of birth, represented as YYYY

      • placeOfBirth: string | null Person's place of birth

    • document: object Verified document

      • number: string | null Document number, [a-zA-Z0-9] characters only

      • type: string | null Document type, one of PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE, VISA, OTHER

      • country: string | null Document issuing country, represented as ISO 3166 alpha-2 code

      • state: string | null Document issuing state, represented as ISO 3166 alpha-2 or alpha-3 code

    • additionalVerifiedData: object Data that has been optionally verified for the session

      • cadastroUnico: object Main container for Cadastro Único Database Verification results

        • validations: object Contains validation rule results

          • processing: object Indicates if registry processing was successful

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isUserDataValid: object Validates input data format (CPF number and date of birth)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotBcpBeneficiary: object Checks if user is NOT receiving BCP benefit (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotBolsaFamiliaBeneficiary: object Checks if user is NOT receiving Bolsa Família (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotSeguroDefesoBeneficiary: object Checks if user is NOT receiving fishermen insurance (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotCadastroUnicoBeneficiary: object Checks if user is NOT in general registry (failure means IS registered)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotAuxilioEmergencialBeneficiary: object Checks if user is NOT receiving emergency aid (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

        • registryResponse: object Contains detailed benefit information from government registries

          • bcpBenefit: object Continuous Cash Benefit details

            • state: string Brazilian state code where benefit is registered

            • benefitNumber: string Unique benefit identification number

            • isInRegistry: boolean Indicates whether user was found in BCP registry

            • beneficiaryNis: string Social Identification Number of beneficiary

            • referenceMonth: string Reference period for data, represented as YYYYMM

            • competenceMonth: string Competence month for payment, represented as YYYYMM

            • installmentValue: string Monetary value of benefit installment

            • municipalityName: string City where beneficiary resides

            • judiciallyGrantedBenefit: string Indicates if benefit was court-ordered

          • bolsaFamiliaBenefit: object Bolsa Família program details

            • qsa: boolean Quadro Social e Administrativo indicator, indicating if the beneficiary is registered as a partner or administrator of a business

            • currentlyActive: boolean Indicates whether benefit is currently active

            • lastBenefitDate: string Date of last benefit payment, represented as DD/MM/YYYY

            • dataInconsistency: boolean Flags data inconsistencies in record

            • firstBenefitDate: string Date user first received benefit

            • lastBenefitValue: string Value of last installment paid

            • last12MonthsData: string Payment history summary for last year

            • lastBenefitPayment: string Details of last payment method

            • wasBenefitRecipient: boolean Indicates whether user ever received this benefit

            • currentlyInBolsaFamilia: boolean Current enrollment status

            • employmentLinkLast5Years: boolean Had formal employment in last 5 years

          • seguroDefesoBenefit: object Artisanal fishermen insurance details

            • isInRegistry: boolean Shows whether user found in Seguro Defeso registry

            • beneficiaryCpf: string CPF number of the beneficiary

            • beneficiaryNis: string NIS number of the beneficiary

            • beneficiaryName: string Full name of the beneficiary

            • beneficiaryState: string State of the beneficiary

            • municipalityCode: string IBGE municipality code

            • municipalityName: string Municipality name

            • benefitReferenceMonth: string Reference month for benefit, represented as DD/MM/YYYY

            • installmentValueReceived: string Amount received for installment

            • fishingRegistrationNumber: string RGP fishing registration number

            • bolsaFamiliaInsuranceSameDate: boolean Indicates if the person received both benefits in same period

          • auxilioEmergencialBenefit: object Emergency aid details

            • state: string State where aid was registered

            • value: string Monetary value of aid installment

            • observation: string Remarks about benefit status

            • installments: string Specific installment number

            • municipality: string City where beneficiary resides

            • classification: string Category of beneficiary

            • isInRegistry: boolean Whether user found in Emergency Aid registry

            • availableMonth: string Month funds became available, represented as MM/YYYY

            • municipalityCode: string Municipality code

    • comments: array (Deprecated) Always returns empty []

    • technicalData: object Technical data object

      • ip: string | null IP of the device from which the verification was made

API call

Below are a sample and an explanation of a GET /decision API call payload, showing only the mandatory parameters for a Cadastro Único Database Verification session.

Depending on your integration configuration, the payload may contain additional parameters. To find more info about those parameters, see the GET sessions/{sessionId}/decision[↗] documentation.

Sample response

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": null,
    "endUserId": null,
    "status": "approved",
    "code": 9001,
    "reason": null,
    "reasonCode": null,
    "decisionTime": "2025-12-10T12:00:00.000+02:00",
    "acceptanceTime": "2025-12-10T11:59:00.000+02:00",
    "submissionTime": "2025-12-10T11:59:30.000000+02:00",
    "person": {
      "firstName": "MARIA",
      "lastName": "SILVA SANTOS",
      "dateOfBirth": "1990-01-15",
      "gender": "F",
      "nationality": "BR",
      "idNumber": "12345678901",
      "yearOfBirth": "1990",
      "placeOfBirth": "BRAZIL"
    },
    "document": {
      "number": "AB123456",
      "type": "ID_CARD",
      "country": "BR",
      "state": "DF"
    },
    "additionalVerifiedData": {
      "cadastroUnico": {
        "validations": {
          "processing": {
            "result": "success",
            "reasons": null
          },
          "isUserDataValid": {
            "result": "success",
            "reasons": null
          },
          "isNotBcpBeneficiary": {
            "result": "failure",
            "reasons": ["User is bcp beneficiary"]
          },
          "isNotBolsaFamiliaBeneficiary": {
            "result": "success",
            "reasons": []
          },
          "isNotSeguroDefesoBeneficiary": {
            "result": "failure",
            "reasons": ["User is seguro defeso beneficiary"]
          },
          "isNotCadastroUnicoBeneficiary": {
            "result": "success",
            "reasons": []
          },
          "isNotAuxilioEmergencialBeneficiary": {
            "result": "failure",
            "reasons": ["User is auxilio emergencial beneficiary"]
          }
        },
        "registryResponse": {
          "bcpBenefit": {
            "state": "SP",
            "benefitNumber": "",
            "isInRegistry": true,
            "beneficiaryNis": "",
            "referenceMonth": "202210",
            "competenceMonth": "202210",
            "installmentValue": "1.212,00",
            "municipalityName": "OSASCO",
            "judiciallyGrantedBenefit": ""
          },
          "bolsaFamiliaBenefit": {
            "qsa": true,
            "currentlyActive": false,
            "lastBenefitDate": "05/12/2022",
            "dataInconsistency": false,
            "firstBenefitDate": "05/12/2022",
            "lastBenefitValue": "",
            "last12MonthsData": "dez/25 - NAO, nov/25 - NAO, out/25 - NAO",
            "lastBenefitPayment": "",
            "wasBenefitRecipient": true,
            "currentlyInBolsaFamilia": false,
            "employmentLinkLast5Years": true
          },
          "seguroDefesoBenefit": {
            "isInRegistry": true,
            "beneficiaryCpf": "12345678901",
            "beneficiaryNis": "12345678901",
            "beneficiaryName": "MARIA SILVA SANTOS",
            "beneficiaryState": "AL",
            "municipalityCode": "1234",
            "municipalityName": "CORURIPE",
            "benefitReferenceMonth": "01/10/2022",
            "installmentValueReceived": "1212.00",
            "fishingRegistrationNumber": "123456",
            "bolsaFamiliaInsuranceSameDate": false
          },
          "auxilioEmergencialBenefit": {
            "state": "PR",
            "value": "300,00",
            "observation": "NAO HA",
            "installments": "9",
            "municipality": "CAMBE",
            "classification": "CADUN NAO BOLSA",
            "isInRegistry": true,
            "availableMonth": "12/2020",
            "municipalityCode": "1234567"
          }
        }
      }
    },
    "comments": [],
    "technicalData": {
      "ip": "192.168.1.1"
    }
  }
}

Response properties explained

  • status: string Status of the response

  • verification: object Verification request decision object. null if decision is not available yet

    • id: string UUID v4 which identifies the verification session

    • attemptId: string UUID v4 of the attempt which received a status (as shown in verification.status field)

    • vendorData: string | null The unique identifier that you created for your end-user. null if not specified

    • endUserId: string | null The UUID that you created for your end-user. null if not specified

    • status: string Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

    • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104, 9121. For more info, see the verification session decision codes

    • reason: string | null Reason why the verification failed

    • reasonCode: integer | null Reason code of the failed verification. For more info, see the possible codes for a failed verification

    • decisionTime: string | null Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

    • acceptanceTime: string Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

    • submissionTime: string Timestamp of when the session was submitted, represented as UTC YYYY-MM-DDTHH:MM:SS.SSSSSS+Timezone Offset (ISO 8601)

    • person: object Data about the verified person

      • firstName: string | null Person's first name as written on the document

      • lastName: string | null Person's last name as written on the document

      • dateOfBirth: string Person's date of birth, represented as YYYY-MM-DD

      • gender: string | null Person's gender, represented as M or F, or null if not present

      • nationality: string | null Person's nationality, represented as ISO 3166 alpha-2 or alpha-3 number

      • idNumber: string | null National identification number

      • yearOfBirth: string | null Person's year of birth, represented as YYYY

      • placeOfBirth: string | null Person's place of birth

    • document: object Verified document

      • number: string | null Document number, [a-zA-Z0-9] characters only

      • type: string | null Document type, one of PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE, VISA, OTHER

      • country: string | null Document issuing country, represented as ISO 3166 alpha-2 code

      • state: string | null Document issuing state, represented as ISO 3166 alpha-2 or alpha-3 code

    • additionalVerifiedData: object Data that has been optionally verified for the session

      • cadastroUnico: object Main container for Cadastro Único Database Verification results

        • validations: object Contains validation rule results

          • processing: object Indicates if registry processing was successful

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isUserDataValid: object Validates input data format (CPF number and date of birth)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotBcpBeneficiary: object Checks if user is NOT receiving BCP benefit (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotBolsaFamiliaBeneficiary: object Checks if user is NOT receiving Bolsa Família (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotSeguroDefesoBeneficiary: object Checks if user is NOT receiving fishermen insurance (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotCadastroUnicoBeneficiary: object Checks if user is NOT in general registry (failure means IS registered)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

          • isNotAuxilioEmergencialBeneficiary: object Checks if user is NOT receiving emergency aid (failure means IS receiving)

            • result: string Validation outcome (success or failure)

            • reasons: array | null Explanations for failure (null or empty if result value is successful)

        • registryResponse: object Contains detailed benefit information from government registries

          • bcpBenefit: object Continuous Cash Benefit details

            • state: string Brazilian state code where benefit is registered

            • benefitNumber: string Unique benefit identification number

            • isInRegistry: boolean Indicates whether user was found in BCP registry

            • beneficiaryNis: string Social Identification Number of beneficiary

            • referenceMonth: string Reference period for data, represented as YYYYMM

            • competenceMonth: string Competence month for payment, represented as YYYYMM

            • installmentValue: string Monetary value of benefit installment

            • municipalityName: string City where beneficiary resides

            • judiciallyGrantedBenefit: string Indicates if benefit was court-ordered

          • bolsaFamiliaBenefit: object Bolsa Família program details

            • qsa: boolean Quadro Social e Administrativo indicator, indicating if the beneficiary is registered as a partner or administrator of a business

            • currentlyActive: boolean Indicates whether benefit is currently active

            • lastBenefitDate: string Date of last benefit payment, represented as DD/MM/YYYY

            • dataInconsistency: boolean Flags data inconsistencies in record

            • firstBenefitDate: string Date user first received benefit

            • lastBenefitValue: string Value of last installment paid

            • last12MonthsData: string Payment history summary for last year

            • lastBenefitPayment: string Details of last payment method

            • wasBenefitRecipient: boolean Indicates whether user ever received this benefit

            • currentlyInBolsaFamilia: boolean Current enrollment status

            • employmentLinkLast5Years: boolean Had formal employment in last 5 years

          • seguroDefesoBenefit: object Artisanal fishermen insurance details

            • isInRegistry: boolean Shows whether user found in Seguro Defeso registry

            • beneficiaryCpf: string CPF number of the beneficiary

            • beneficiaryNis: string NIS number of the beneficiary

            • beneficiaryName: string Full name of the beneficiary

            • beneficiaryState: string State of the beneficiary

            • municipalityCode: string IBGE municipality code

            • municipalityName: string Municipality name

            • benefitReferenceMonth: string Reference month for benefit, represented as DD/MM/YYYY

            • installmentValueReceived: string Amount received for installment

            • fishingRegistrationNumber: string RGP fishing registration number

            • bolsaFamiliaInsuranceSameDate: boolean Indicates if the person received both benefits in same period

          • auxilioEmergencialBenefit: object Emergency aid details

            • state: string State where aid was registered

            • value: string Monetary value of aid installment

            • observation: string Remarks about benefit status

            • installments: string Specific installment number

            • municipality: string City where beneficiary resides

            • classification: string Category of beneficiary

            • isInRegistry: boolean Whether user found in Emergency Aid registry

            • availableMonth: string Month funds became available, represented as MM/YYYY

            • municipalityCode: string Municipality code

    • comments: array (Deprecated) Always returns empty []

    • technicalData: object Technical data object

      • ip: string | null IP of the device from which the verification was made

Veriff Customer Portal

You can find the verification session related info, including the decision, in the Veriff Customer Portal → Session page → Webhooks tab.

→ See Review verification in Veriff Customer Portal about how to view the session info in the Veriff Customer portal

Status and reason codes

For an approved session, see:

  • verification.code about verification session decision code, one of 9001, 9102, 9103, 9104, 9121

  • verification.status about verification status, one of approved, declined, resubmission_requested, expired, abandoned

If the Cadastro Único Database Verification session was declined or resubmission_requested, you can find additional information by checking:

  • verification.reason for the reason why the verification failed

  • verification.reasonCode for reason code of the failed verification and cross-reference it with Granular reason codes (table)

verification.status

verification.reasonCode

verification.reason

What does it mean?

declined

570

IS_BOLSA_FAMILIA_BENEFICIARY

User is receiving Bolsa Família benefits

declined

570

IS_BCP_BENEFICIARY

User is receiving continuous cash benefit

declined

570

IS_SEGURO_DEFESO_BENEFICIARY

User is receiving artisanal fishermen insurance benefits

declined

570

IS_AUXILIO_EMERGENCIAL_BENEFICIARY

User is receiving emergency aid benefits

declined

570

IS_CADASTRO_UNICO_BENEFICIARY

User is registered in the general registry

declined

529

INVALID_CPF

CPF format is invalid. Ensure 11-digit number without punctuation

declined

529

INVALID_DATE_OF_BIRTH

Date of birth format is invalid

declined

566

UNAVAILABLE_REGISTRY_PROVIDER

Registry service unavailable

declined

566

TIMEOUT_ERROR

Registry service timed out

declined

566

INTERNAL_ERROR

An internal technical error occurred

The table above aims to list the most common reasons why you may see the decline reason for a Cadastro Único Database Verification session. However, the session may be declined due to a reason that is not inherently Cadastro Único Database Verification verification related (e.g. uploaded document’s quality is low). In that case, to find info about the codes you are seeing, refer to:

Additional information

Best practices

  1. CPF format validation: Always validate CPF format before sending to Veriff. CPF must be exactly 11 digits without any punctuation (dots, hyphens, or spaces). Invalid format will result in session decline with code 529.

  2. Error handling for registry issues: Implement proper session handling flow when possibly legitimate end-user’s session is declined due to the third-party service provider having issues, as indicated by session code 566.

  3. Error handling: Implement proper error handling for all possible validation results (format issues, registry timeouts and issues, etc.)

  4. Webhook security: Secure your webhook endpoint and verify request signatures

  5. User experience: Provide clear feedback to users about validation results

  6. Ensure backwards compatibility for webhooks and API connections

Changelog

Date

Description

Dec 16, 2025

Minor updates to the text formatting

Dec 15, 2025

Documentation published