Brazilian CPF Biometric Database Check

The CPF Biometric Database Check enables identity verification by matching user-provided CPF numbers and biometric data (facial images) against Brazil's official government databases. This solution provides higher accuracy verification by cross-referencing user information with trusted government sources, including CPF status validation, name verification, date of birth confirmation, and facial biometric matching against official records stored in the National Driver's License (Renach) database.

*CPF Biometric Database Check can be:

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

• used separately as a standalone check. In this case the whole flow is done over the API.

CPF Biometric Database Check is available via API, web flow (web SDKs), and native SDKs.

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 → Webhook tab, inside a webhook payload.

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

Types of validation

Contact your solutions engineer for info and configuration.

Prerequisites

1. You have an integration set up with Veriff

2. The CPF Biometric Database Check feature is configured for that integration by your Solutions Engineer

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

4. If using the API, you are ready to collect and send Veriff your end-user’s data (CPF number, facial biometric data)

5. If using the 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

End-user data sources

The checks are performed on end-user’s data, which can come from two data sources: document data and initData.

Irrespective of the data source and the purpose for the database check, idNumber is always required.

The minimum data combinations to run a successful check are:

• CPF number

• CPF number + First Name

• CPF number + Last Name

• CPF number + Date of Birth

Document data

This means that the checks are completed using the data extracted from the end-user’s document. Fields extracted from the document and applicable for database check:

• CPF number

• first name and last name

• date of birth

If you include initData for a session that is done using document capture, the initData takes precedence.

initData

This means that the checks completed using the data you input during the session creation, i.e. the parameters you specify in the POST /sessions request. Parameters you can define in the request:

In verification.person object:

• idNumber aka person’s CPF number (mandatory)

• firstName

• lastName

• dateOfBirth

Flow overview

The flow is a bit different, depending on the method you are using to verify your end-users with Veriff. The solution works via both SDKs and API, with the SDK automatically handling the document capture interface for CPF extraction, while the API requires manual collection and submission of the CPF number and images.

Use via SDKs

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

2. Capture end-user’s document / selfie images with Veriff’s SDKs:

   • Send the end-user through the verification flow to capture the images (using the preferred Veriff SDK).

   • You need the session URL generated in step 1 to use the SDKs (found in response payload as verification.url).

3. The SDK automatically presents the document capture interface for CPF extraction.

4. Session will be submitted automatically once the end-user takes and submits necessary images.

5. Receive the results from Veriff via decision webhook or poll them via GET sessions/{sessionId}/decision[↗] endpoint.

Use via API

Standalone CPF Biometric Database Check verification

Use when you only need to do the CPF Biometric Database Check without collecting document images.

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

   • Make sure to pass the mandatory person.idNumber parameter with the CPF number value

   • Make sure to pass person.dateOfBirth parameter if doing date of birth match validation

   • Make sure to pass either person.firstName or person.lastName parameter if doing name match validation

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

   • 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

Date of birth match validation and name match validations are enabled

curl -X POST \
  --url '/v1/sessions/' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "verification": {
      "person": {
        "idNumber": "12345678901",
        "firstName": "João",
        "lastName": "Silva",
        "dateOfBirth": "1990-01-15"
      },
      "vendorData": "12345678",
      "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
    }
  }'

Session creation JSON payload:

{
  "verification": {
    "person": {
      "idNumber": "12345678901",
      "firstName": "João",
      "lastName": "Silva",
      "dateOfBirth": "1990-01-15"
    },
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
  }
}

2. Use your image-capturing method, or prepare previously collected end-user selfie image(s).

3. Upload the end-user's media via POST /sessions/{sessionId}/media[↗] call.

   • Specify the image.context as appropriate for the image (face) (see Context types (image, video) for more info about image context types)

   Media upload bash example

   curl -X POST \
     --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media' \
     -H 'X-AUTH-CLIENT: API-KEY' \
     -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
     -H 'Content-Type: application/json' \
     -d '{
       "image": {
         "context": "face-selfie",
         "content": "base64-encoded-selfie-data",
         "timestamp": "2024-01-15T10:31:00Z"
       }
     }'
   

   Media upload JSON payload

   {
     "image": {
       "context": "face-selfie",
       "content": "base64-encoded-selfie-data",
       "timestamp": "2024-01-15T10:31:00Z"
     }
   }
   

4. Patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call.

Session status update bash example

curl -X PATCH \
  --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "submitted"
  }'

Session status update JSON payload

{
  "status": "submitted"
}

5. Check the decision data and/or session related info from the decision webhook and/or query the data from the GET sessions/{sessionId}/decision[↗] endpoint.

CPF Biometric Database Check with document verification

When including document images for additional data extraction.

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

   • Make sure to pass the mandatory person.idNumber parameter with the CPF number value

   • Make sure to pass person.dateOfBirth parameter if doing date of birth match validation

   • Make sure to pass either person.firstName or person.lastName parameter if doing name match validation

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

   • 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

   Date of birth match validation and name match validations are enabled

   curl -X POST \
     --url '/v1/sessions/' \
     -H 'X-AUTH-CLIENT: API-KEY' \
     -H 'Content-Type: application/json' \
     -d '{
       "verification": {
         "person": {
           "firstName": "João",
           "lastName": "Silva", 
           "idNumber": "12345678901",
           "dateOfBirth": "1990-01-15"
         },
         "vendorData": "12345678",
         "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
       }
     }'
   

   Session creation JSON payload

   {
     "verification": {
       "person": {
         "firstName": "João",
         "lastName": "Silva", 
         "idNumber": "12345678901",
         "dateOfBirth": "1990-01-15"
       },
       "vendorData": "12345678",
       "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
     }
   }
   

2. Use your image-capturing method, or prepare previously collected end-user selfie and document image(s).

3. Upload the end-user's media via POST /sessions/{sessionId}/media[↗] call.

   • Specify the image.context as appropriate for the image (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 '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media' \
     -H 'X-AUTH-CLIENT: API-KEY' \
     -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
     -H 'Content-Type: application/json' \
     -d '{
       "image": {
         "context": "face-selfie",
         "content": "base64-encoded-selfie-data",
         "timestamp": "2024-01-15T10:31:00Z"
       }
     }'
   

   Media upload JSON payload

   {
     "image": {
       "context": "face-selfie",
       "content": "base64-encoded-selfie-data",
       "timestamp": "2024-01-15T10:31:00Z"
     }
   }
   

4. Patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call

   Session status update bash example

   curl -X PATCH \
     --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
     -H 'X-AUTH-CLIENT: API-KEY' \
     -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
     -H 'Content-Type: application/json' \
     -d '{
       "status": "submitted"
     }'
   

   Session status update JSON payload

   {
     "status": "submitted"
   }
   

5. Check the decision data and/or session related info from the decision webhook and/or query the data from the GET sessions/{sessionId}/decision[↗] endpoint. 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 endpoint (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 CPF Biometric Database Check is returned in verification.additionalVerifiedData.biometricRegistryValidationResults object. It contains an object BR, indicating the country of the registry, and inside isFaceMatch, isNameMatch and isDobMatch booleans.

• isFaceMatch indicates that the end-user’s selfie matches the portrait in the database

• isNameMatch and isDobMatch results (true, false) are relevant if the name match validation and date of birth validation have been enabled for the integration. Otherwise they return null.

{
  "verification": {
    "additionalVerifiedData":{
        "biometricRegistryValidationResults": {
          "BR": {
            "isNameMatch": true,
            "isDobMatch": true,
            "isFaceMatch": true
          }
        }
    }
  }
}

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 CPF Biometric Database Check 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",
    "code": 9001,
    "person": {
      "firstName": "JOÃO",
      "lastName": "SILVA",
      "dateOfBirth": "1990-01-15",
      "gender": null,
      "nationality": null,
      "idNumber": "12345678901",
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "reason": null,
    "status": "approved",
    "comments": [],
    "document": {
      "number": null,
      "type": null,
      "country": null,
      "state": null
    },
    "reasonCode": null,
    "vendorData": "12345678",
    "acceptanceTime": "2024-01-15T09:30:00.000Z",
    "submissionTime": "2024-01-15T10:16:15.736755Z",
    "decisionTime": "2024-01-15T10:20:00.000Z",
    "additionalVerifiedData": {
      "biometricRegistryValidationResults": {
        "BR": {
          "isFirstNameMatch": true,
          "isLastNameMatch": true,
          "isDobMatch": true,
          "isFaceMatch": true
          }
        }
      }
    },
    "technicalData": {
        "ip": "186.153.67.122"
    }
  }
}

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

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

  • reason: string 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

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

  • 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 Data about the 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. For more info, see the Supported document types for IDV article

    • 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

  • 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

  • acceptanceTime: string | null 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)

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

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

  • additionalVerifiedData: object Data that has been optionally verified for the session. Optional, depending on the integration

    • biometricRegistryValidationResults: object Biometric registry validation container

      • BR: object Brazil-specific validation results

        • isFirstNameMatch: boolean First name match result, null if first name match validation was not enabled or the check could not be completed

        • isLastNameMatch: boolean Last name match result, null if last name match validation was not enabled or the check could not be completed

        • isDobMatch: boolean Date of birth match result, null if date of birth match validation was not enabled or the check could not be completed

        • isFaceMatch: boolean Facial biometric match result, null if selfie not sent or the check could not be completed

  • technicalData: object Technical data object

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

Decline due to registry issue

The session may fail because of issues on the registry side, meaning that a legitimate user may get a decline decision. Pay attention to such occurrences and implement session handling flows.

In such sessions, the relevant info is in:

• verification :

  • reason : Registry provider error occurred while connecting to the registry

  • reasonCode: 566

{
  "status": "success",
  "verification": {
    "acceptanceTime": "2025-11-14T11:11:04.131655Z",
    "submissionTime": "2025-11-14T11:11:08.787231Z",
    "decisionTime": "2025-11-14T11:11:12.627776Z",
    "code": 9102,
    "id": "5614272e-8946-4b74-bd8d-87823ebeb87a",
    "vendorData": null,
    "endUserId": null,
    "status": "declined",
    "reason": "Registry provider error occurred while connecting to the registry",
    "reasonCode": 566,
    "person": {...},
    "document": {...},
    "comments": [],
    "additionalVerifiedData": {
      "biometricRegistryValidationResults": {
        "BR": {
          "isNameMatch": null,
          "isDobMatch": null,
          "isFaceMatch": null
        }
      }
    },
    "attemptId": "ad8a5b47-1062-4e7b-97a1-131e3b279d75"
  },
  "technicalData": {
    "ip": null
  }
}

API call

Below is an example and an explanation of the GET /decision API call payload showing only the mandatory parameters for a CPF Biometric Database Check 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",
    "code": 9001,
    "person": {
      "firstName": "JOÃO",
      "lastName": "SILVA",
      "dateOfBirth": "1990-01-15",
      "gender": null,
      "nationality": null,
      "idNumber": "12345678901",
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "reason": null,
    "status": "approved",
    "comments": [],
    "document": {
      "number": null,
      "type": null,
      "country": null,
      "state": null
    },
    "reasonCode": null,
    "vendorData": "12345678",
    "acceptanceTime": "2024-01-15T09:30:00.000Z",
    "submissionTime": "2024-01-15T10:16:15.736755Z",
    "decisionTime": "2024-01-15T10:20:00.000Z",
    "additionalVerifiedData": {
      "biometricRegistryValidationResults": {
        "BR": {
          "isFirstNameMatch": true,
          "isLastNameMatch": true,
          "isDobMatch": true,
          "isFaceMatch": true
          }
        }
      }
    },
    "technicalData": {
        "ip": "186.153.67.122"
    }
  }
}

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

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

  • reason: string 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

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

  • 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 Data about the 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. For more info, see the Supported document types for IDV article

    • 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

  • 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

  • acceptanceTime: string | null 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)

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

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

  • additionalVerifiedData: object Data that has been optionally verified for the session. Optional, depending on the integration

    • biometricRegistryValidationResults: object Biometric registry validation container

      • BR: object Brazil-specific validation results

        • isFirstNameMatch: boolean First name match result, null if first name match validation was not enabled or the check could not be completed

        • isLastNameMatch: boolean Last name match result, null if last name match validation was not enabled or the check could not be completed

        • isDobMatch: boolean Date of birth match result, null if date of birth match validation was not enabled or the check could not be completed

        • isFaceMatch: boolean Facial biometric match result, null if selfie not sent or the check could not be completed

  • 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 → Webhooks tab.

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 CPF Biometric Database Check 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).

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

• Verification session status codes (table)

• Verification session decision codes (table)

• Granular reason codes (table)

Additional information

Best practices

1. CPF number format validation: remove special characters from CPF (dots, hyphens) before processing.

2. CPF number validation: ensure that the CPF number is valid before submitting to Veriff. This will reduce the possibility of session going to resubmission_requested.

3. Ensure that the end-user has a driver’s licence: in order for the face match check to work, the end-user must own a driver’s licence. To mitigate risk of errors and unsuccessful validations, Veriff recommends you implement measures that ensure before the check that the end-user has a driver’s licence.

4. Selfie image quality: ensure that end-user’s selfie is of good quality. This will reduce the possibility of session going to resubmission_requested.

5. Document image quality: ensure that end-user’s document image is of good quality. This will reduce the possibility of session going to resubmission_requested.

6. Error handling: implement proper error handling for all possible validation results.

7. Session declined due to third-party provider 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.

8. Webhook security: secure your webhook endpoint and verify request signatures.

9. User experience: provide clear feedback to users about validation results.

10. Ensure backwards compatibility for webhooks and API connections

FAQ

Changelog