--- title: "Cadastro Único Database Verification" slug: "brazilian-cadastro-unico-database-verification" description: "Validate Brazilian users against social benefit registries with Cadastro Único Database Verification for compliance, fraud prevention, and real-time checks." updated: 2026-01-15T11:07:18Z published: 2026-01-15T11:07:18Z --- > ## Documentation Index > Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt > Use this file to discover all available pages before exploring further. # Cadastro Único Database Verification | 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**. > [!NOTE] > Contact your **solutions engineer** for info and configuration. --- ## Prerequisites - You have an [integration set up](https://devdocs.veriff.com/v1/docs/how-to-create-an-integration) with Veriff - The **feature is configured** for that integration **by your Solutions Engineer** - You have configured the [decision webhook](https://devdocs.veriff.com/v1/docs/decision-webhook) to get responses from Veriff (see the how-to in webhooks’ [Set up webhooks](https://devdocs.veriff.com/docs/webhooks-guide#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](https://devdocs.veriff.com/apidocs/v1sessions) 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](https://devdocs.veriff.com/apidocs)[↗] 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](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidcollected-data-1)[↗] for improved fraud detection **Session creation bash example** ```bash 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** ```json {  "verification": {    "callback": "https://example.com/webhook",    "person": {      "idNumber": "12345678901",      "dateOfBirth": "1990-01-15"    }  } } ``` 1. Patch session status to `submitted` status via [PATCH /sessions/{sessionId}](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsid-2)[↗] **Session update bash example** ```bash 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** ```json {  "status": "submitted" } ``` 1. Check the decision data and/or session related info from the decision webhook payload (see an [example below](/v1/docs/brazilian-cadastro-unico-database-verification#webhook-payload)) and/or query the data from the GET /sessions/{sessionId}/decision endpoint (see an [example below](/v1/docs/brazilian-cadastro-unico-database-verification#api-call)). Solution-specific overview of what to expect is provided below in [Solution-specific parameters](/v1/docs/brazilian-cadastro-unico-database-verification#solutionspecific-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](https://devdocs.veriff.com/apidocs)[↗] 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](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidcollected-data-1)[↗] for improved fraud detection **Session creation bash example** ```bash 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** ```json {  "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)](/v1/docs/context-types-image-video-1) for more info about image context types) **Media upload bash example** ```bash 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** ```json {  "image": {    "data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...",    "context": "document-front"  } } ``` 1. Patch session status to `submitted` status via [PATCH /sessions/{sessionId}](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsid-2)[↗] **Session update bash example** ```bash 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** ```json {  "status": "submitted" } ``` 1. Check the decision data and/or session related info from the decision webhook payload (see an [example below](/v1/docs/brazilian-cadastro-unico-database-verification#webhook-payload)) and/or query the data from the GET /sessions/{sessionId}/decision endpoint (see an [example below](/v1/docs/brazilian-cadastro-unico-database-verification#api-call)). Solution-specific overview of what to expect is provided below in [Solution-specific parameters](/v1/docs/brazilian-cadastro-unico-database-verification#solutionspecific-parameters) section. --- ## Find decision and/or session related info You can get the data from three sources: - Receive the decision webhook ([example below](/v1/docs/brazilian-cadastro-unico-database-verification#webhook-payload)) - Query the results via GET /sessions/{sessionId}/decision ([example below](/v1/docs/brazilian-cadastro-unico-database-verification#api-call)) - 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](/v1/docs/brazilian-cadastro-unico-database-verification#request-properties-explained) 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](/v1/docs/brazilian-cadastro-unico-database-verification#request-properties-explained) 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** ```json {    "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 > [!NOTE] > 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](/v1/docs/decision-webhook) documentation. #### Sample request ```json {  "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](/v1/docs/verification-session-decision-codes-table) - `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 > [!NOTE] > 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](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] documentation. #### Sample response ```json {  "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](/v1/docs/verification-session-decision-codes-table) - `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*](/v1/docs/how-to-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)](https://devdocs.veriff.com/v1/docs/granular-reason-codes) | `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: - [Granular reason codes (table)](https://devdocs.veriff.com/v1/docs/granular-reason-codes) - [Verification session status codes (table)](https://devdocs.veriff.com/v1/docs/verification-session-status-codes-table) - [Verification session decision codes (table)](https://devdocs.veriff.com/v1/docs/verification-session-decision-codes-table) --- ## 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**](/v1/docs/backwards-compatible-changes) for webhooks and API connections --- ## Changelog | Date | Description | | --- | --- | | Jan 15, 2026 | Indentation in payload examples and explanations updated | | Dec 16, 2025 | Minor updates to the text formatting | | Dec 15, 2025 | Documentation published | Veriff customer back-office, a dashboard where you can see your end-users' verification data. Depending on your setup, you may be required to access the environment via station.veriff.com or hub.veriff.com. Always **check your sign-up email** and make sure that you **log in via correct address**.