Registraduría Verification

Registraduría Verification enables the verification of Colombian identity documents against the Registraduría Nacional del Estado Civil de Colombia database.

It validates that the end-user’s full name matches the info in the database, that the presented document is valid, and checks whether the person is registered as deceased.

Registraduría Verification is available via API, web flow, and native SDKs.

*Registraduría Verification can be:

• an add-on to your document-based identity verification (IDV) solution (therefore using the existing integration), or

• used separately as a standalone check. In this case the whole flow is done over the API, using a separate integration that you set up with Veriff’s help.

Contact your solutions engineer for info and configuration.

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, in All Verifications > 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. Also, any document number and name information provided via initData during session creation is echoed back in the response.

Prerequisites

• You have an integration set up with Veriff

• The database check 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)

• If using the API, you are ready to collect and send Veriff your end-user’s data.

  • 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 “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.

Note that in order for the solution to work, the required data needs to be available either via document (is extracted during verification flow) or via initData (is passed by you in POST /session payload).

Document data

This is data that is extracted from the end-user’s document.

Document data as data source can be used when the Registraduría Verification is use as:

• an add-on to document-based IDV via SDK,

• an add-on to document-based IDV via API,

• a standalone check via API.

In order for the solution to work, all of the following data must be available on the document:

• first name

• last name

• document number

• card type

• first issue date

InitData

This is data that you provide when creating a verification session, i.e. the parameters you specify in the POST /sessions request.

initData as data source can be used when the Registraduría Verification is used as:

• an add-on to document-based IDV via API,

• a standalone check via API.

In order for the solution to work, the following parameters must be populated in initData:

• end-user’s first name via person.firstName

• end-user’s last name via person.lastName

• document number via document.number

• document type via document.idCardType (see Key terminology table for card types’ abbreviations)

• document first issue date via document.firstIssue

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 document data extraction, while the API requires manual collection and submission of the initData or uploading document images for document data extraction.

Use via SDKs

1. Generate a verification session using the API keys and the baseURL of your integration (see the API Documentation and API Reference how to find these).

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

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

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

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

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

Use via API

Standalone Registraduría Verification verification

Use when you only need to verify end-user’s data without collecting and sending document images.

1. Generate a verification session using the API keys and the baseURL of your integration (see the API Documentation and API Reference how to find these)

   1. Make sure to pass the mandatory document.number, document.idCardType, document.firstIssue, person.firstName, and person.lastName parameters.

   2. Registraduría Verification supports only Colombian identity documents.

   3. Veriff strongly recommends you create and send the vendorData and endUserId.

Session creation bash example

curl -X POST \
  --url 'https://exampleURL.com/v1/sessions' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "verification": {
      "callback": "https://exampleURL.com",
      "person": {
        "lastName": "Romero",
        "firstName": "Juan"
      },
      "document": {
        "number": "1234567890",
        "country": "CO",
        "firstIssue": "2013-04-09",
        "idCardType": "CC"
      },
      "vendorData": "12345678"
    }
  }'

Session creation json example

{
  "verification": {
    "callback": "https://exampleURL.com",
    "person": {
      "lastName": "Romero",
      "firstName": "Juan"
    },
    "document": {
      "number": "0987654321",
      "country": "CO",
      "firstIssue": "2013-04-09",
      "idCardType": "CC"
    },
    "vendorData": "12345678"
  }
}

2. Next, patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call.

   2. This endpoint requires endpoint level authentication via x-hmac-signature header. See HMAC Authentication and Endpoint Security article for general info about signature creation.

Session update bash example

curl -X PATCH \
  --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-hmac-signature: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "verification": {
      "status": "submitted"
    }
  }'

Session update json example

{
  "verification": {
    "status": "submitted"
  }
}

3. Finally, 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 the Find decision and/or session related info > Solution-specific parameters section.

Registraduría Verification with document verification

Use when collect and send document images to verify end-user’s data.

1. Generate a verification session using the API keys and the baseURL of your integration (see the API Documentation and API Reference how to find these)

   1. Registraduría Verification supports only Colombian identity documents.

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

   3. Do not include initData values because all the necessary info will be extracted from the document images.

Session creation bash example

curl -X POST \
  --url 'https://exampleURL.com/v1/sessions' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "verification": {
      "callback": "https://exampleURL.com",
      "vendorData": "12345678"
    }
  }'

Session creation json example (empty verification object)

{
  "verification": {
    "callback": "https://exampleURL.com",
    "vendorData": "12345678"
  }
}
    

2. Next, use your image-capturing method to collect document images and then send them via POST /sessions/{sessionId}/media[↗] call.

   2. Specify the image.context as appropriate for the image (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: your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-hmac-signature: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "image": {
      "context": "document-front",
      "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
    }
  }'

Media upload json example

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

3. Next, patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call.

   2. This endpoint requires endpoint level authentication via x-hmac-signature header. See HMAC Authentication and Endpoint Security article for general info about signature creation.

Session update bash example

curl -X PATCH \
  --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-hmac-signature: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "verification": {
      "status": "submitted"
    }
  }'

Session update json example

{
  "verification": {
    "status": "submitted"
  }
}

4. Finally, 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 the Find decision and/or session related info > Solution-specific parameters section.

Find decision and/or session related info

You can get the data from three sources:

• Receive the decision webhook (full example with placeholder values below)

• Query the results via GET /sessions/sessionId/decision endpoint (full example with placeholder values below)

• View the session in Veriff Customer Portal > All Verifications > session > Webhooks tab.

Solution-specific parameters

Info related to Registraduría Verification is returned in registryValidation object. Parameters inside the object convey whether it was possible to validate that the end-user’s full name matches the info in the database and that the presented document is valid, and whether the person is registered as deceased.

Sample payload of registryValidation object

All strings and IDs are placeholder values used for illustrative purposes only. Your production payload will contain real-time data passed by the system about validation results.

See the Request properties explained section below for info about the properties.

Person exists in the database, is not deceased

{
  "verification": {
    "additionalVerifiedData": {
      "registryValidation": {
        "countryRegistry": "CO",
        "registryName": "resigo",
        "fullNameSimilarity": 100,
        "documentValid": true,
        "personIsAlive": true
      }
    }
  }
}

Person is deceased

{
  "verification": {
    "additionalVerifiedData": {
      "registryValidation": {
        "countryRegistry": "CO",
        "registryName": "resigo",
        "fullNameSimilarity": 100,
        "documentValid": true,
        "personIsAlive": false
      }
    }
  }
}

Registry did not respond

{
  "verification": {
    "additionalVerifiedData": {
      "registryValidation": {
        "countryRegistry": null,
        "registryName": null,
        "fullNameSimilarity": null,
        "documentValid": null,
        "personIsAlive": null,
        "errors": ["Unable to get response from registry"]
      }
    }
  }
}

Webhook payload

The example below uses placeholder data to show all webhook mandatory parameters and possible Registraduría Verification fields.

Depending on your integration’s configuration, your production payload may contain additional parameters; for info on fields from other solutions, see the decision webhook’s documentation.

Sample request

{
  "status": "success",
  "verification": {
      "id": "f3a8b7c2-d4e1-4f92-a8b3-c5d6e7f8a9b0",
      "attemptId": "b9c8d7e6-f5a4-4b32-9c8d-7e6f5a4b3c2d",
      "vendorData": "12345678",
      "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
      "status": "approved",
      "code": 9001,
      "reason": null,
      "reasonCode": null,
      "acceptanceTime": "2026-02-18T13:39:54.401658Z",
      "submissionTime": "2026-02-18T13:40:22.784253Z",
      "decisionTime": "2026-02-18T13:41:47.173826Z",
      "person": {
          "firstName": "JUAN",
          "lastName": "ROMERO",
          "dateOfBirth": "1995-01-03",
          "gender": null,
          "nationality": "CO",
          "idNumber": "1234567890",
          "yearOfBirth": "1995",
          "placeOfBirth": "BARRANQUILLA (ATLANTICO)"
      },
      "document": {
          "number": "0987654321",
          "type": "ID_CARD",
          "country": "CO",
          "state": null,
          "validFrom": "2013-04-09"
      },
      "additionalVerifiedData": {
          "registryValidation": {
              "countryRegistry": "CO",
              "registryName": "resigo",
              "fullNameSimilarity": 100,
              "documentValid": true,
              "personIsAlive": true
        }
      },
      "comments": []
  },
  "technicalData": {
    "ip": "190.25.100.50"
  } 
}

Request properties explained

• status: string Status of the response

• verification: object | null 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, expired, abandoned

  • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104. For more info, see the verification session status 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

  • 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)

  • decisionTime: string | null Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+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

    • fullName: string | null Full name of the person

    • idNumber: string | null National identification number

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

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

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

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

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

    • addresses: array A map with keys for fullAddress

      • fullAddress: string | null Address as single string

    • citizenship: null Deprecated, always returns null

    • pepSanctionMatch: string | null Legacy field, may return incorrect result, should be ignored

  • document: object Data about verified document

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

    • type: string | null Document type

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

    • validFrom: string | null Document is valid from date, represented as YYYY-MM-DD

    • validUntil: string | null Document is valid until date, represented as YYYY-MM-DD

    • 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

    • registryValidation: Container for registry validation results

      • countryRegistry: string | null Country of the registry, always CO

      • registryName: string | null Name of the registry, always resigo

      • fullNameSimilarity: number | null Similarity of the full name in the registry to the full name in the document, typically 0-100

      • documentValid: boolean | null Indicates if the document is valid in the registry

      • personIsAlive: boolean | null Indicates if the person is alive in the registry

      • error: array Only sent if the registry did not respond

  • 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

The example below uses placeholder data to show all the response’s mandatory parameters and possible Registraduría Verification fields.

Depending on your integration’s configuration, your production payload may contain additional parameters; for info on fields from other solutions, see the decision webhook’s documentation.

Sample response

{
  "status": "success",
  "verification": {
      "id": "f3a8b7c2-d4e1-4f92-a8b3-c5d6e7f8a9b0",
      "attemptId": "b9c8d7e6-f5a4-4b32-9c8d-7e6f5a4b3c2d",
      "vendorData": "12345678",
      "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
      "status": "approved",
      "code": 9001,
      "reason": null,
      "reasonCode": null,
      "acceptanceTime": "2026-02-18T13:39:54.401658Z",
      "submissionTime": "2026-02-18T13:40:22.784253Z",
      "decisionTime": "2026-02-18T13:41:47.173826Z",
      "person": {
          "firstName": "JUAN",
          "lastName": "ROMERO",
          "dateOfBirth": "1995-01-03",
          "gender": null,
          "nationality": "CO",
          "idNumber": "1234567890",
          "yearOfBirth": "1995",
          "placeOfBirth": "BARRANQUILLA (ATLANTICO)"
      },
      "document": {
          "number": "0987654321",
          "type": "ID_CARD",
          "country": "CO",
          "state": null,
          "validFrom": "2013-04-09"
      },
      "additionalVerifiedData": {
          "registryValidation": {
              "countryRegistry": "CO",
              "registryName": "resigo",
              "fullNameSimilarity": 100,
              "documentValid": true,
              "personIsAlive": true
        }
      },
      "comments": []
  },
  "technicalData": {
    "ip": "190.25.100.50"
  } 
}

Response properties explained

• status: string Status of the response

• verification: object | null 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, expired, abandoned

  • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104. For more info, see the verification session status 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

  • 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)

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

  • person: object Data about the verified person. Contains data only if document was used for verification.

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

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

    • fullName: string | null Full name of the person

    • idNumber: string | null National identification number

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

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

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

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

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

    • addresses: array A map with keys for fullAddress

      • fullAddress: string | null Address as single string

    • citizenship: null Deprecated, always returns null

    • pepSanctionMatch: string | null Legacy field, may return incorrect result, should be ignored

  • document: object Verified document. Contains data only if document was used for verification.

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

    • type: string | null Document type

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

    • validFrom: string | null Document is valid from date, represented as YYYY-MM-DD

    • validUntil: string | null Document is valid until date, represented as YYYY-MM-DD

    • 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

    • registryValidation: Container for registry validation results

      • countryRegistry: string Country of the registry

      • registryName: string Name of the registry

      • fullNameSimilarity: number Similarity of the full name in the registry to the full name in the document

      • documentValid: boolean Indicates if the document is valid in the registry

      • personIsAlive: boolean Indicates if the person is alive in the registry

      • error: array Only sent if the registry did not respond

  • 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, under the session details in Station tab.

Status and reason codes

For an approved session, see:

• verification.code: 9001

• verification.status: approved

If the Registraduría Verification session was declined or resubmission_requested, you can find additional information by checking:

• verification.reason for the cause of failure

• verification.reasonCode for the numeric reason code

The table above aims to list the most common reasons why you may see the decline reason for a Registraduría Verification session. However, the session may be declined due to a reason that is not inherently  Registraduría 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

Troubleshooting

Issues that you may encounter in session results.

Best practices

• First issue date format validation: always use YYYY-MM-DD format for the document.firstIssue field to avoid document validity check failures.

• Document type validation: ensure that you are passing a supported Colombia document type in document.idCardType

• 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.

• Error handling: Implement proper error handling for all possible validation results.

• 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.

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

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

• Ensure backwards compatibility for webhooks and API connections.

Changelog