General FAQ

X-signature is a solution used before the X-HMAC-SIGNATURE header was implemented. By default, Veriff enforces sending X-HMAC-signature, but it is possible that the requests you send overwrite it to X-signature.

If you see this returned for you POST /session request, you can validate it (it is a MAC signature, combination of sha256 hash of payload and master secret (in this order). But you should avoid the legacy solution and make sure that your payloads are always signed with the X-HMAC-signature, this way Veriff will also always return X-HMAC-signature.

It is a MAC signature, combination of sha256 hash of payload and master secret (in this order).

Different API endpoints require you sign different parameters to generate a X-HMAC-signature.

As a rule of thumb, it is:

• POST* / PATCH request: request body signed with shared secret key

• GET / DELETE request: session ID signed with shared secret key

*Exception is POST /sessions which does not require an X-HMAC-SIGNATURE.

See each endpoint’s documentation in Veriff API Documentation and API Reference portal for exact info.

It may be because you have an old integration that was created when customers were required to define decision webhook URL in the Veriff Customer Portal. This used to be a requirement to get responses via this API endpoint.

The URL for API requests consist of the following elements: API URL + v1 + path + query parameters (if needed)

Example: https://baseURL/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/curp-registry?version=1.0.0

1. The API URL consist of the integration’s baseURL + v1 . BaseURL always comes from the Integration’s page in Veriff Customer Portal:

2. The path (and query parameters) you need to take from specific API endpoint’s documentation[↗]

See Veriff Release Notes page

We give a positive conclusive decisions (status approved, code 9001) when:

• Photos and videos uploaded to Veriff

• The data on the document is readable and matches throughout the document

• The end-user's portrait photo is recognizable

• The end-user on the portrait photo corresponds to the person on the document photo

• The document is valid (dates, etc.,)

A positive decision means that the person was verified. The verification process is complete. Accessing the session URL again will tell the end-user that nothing more is to be done.

We give a negative conclusive decision (status declined, code 9102) when:

• Physical document not used

• Suspected document tampering

• Person showing the document does not appear to match document photo

• Suspicious behaviour

• Velocity/abuse

• Known fraud

A negative decision means that the person has not been verified. The verification process is complete. Either it was a fraud case or some other severe reason that the person can not be verified. Veriff recommends to investigate the session. If you decide to give the end-user another try, you need to create a new session.

We give an inconclusive decision (status resubmission_requested, code 9103), when:

• Video and/or photos missing

• Face not clearly visible

• Full document not visible

• Poor image quality

• Document damaged

• Document type not supported

• Document expired

When verifications receive a resubmission_requested decision from Veriff, it is strongly advised that you inform the end-user about the reasons for the verification failure and provide suggestions on how to improve their next attempt. This communication can be conducted through email, SMS, and/or within your platform to ensure better visibility.

For resubmitted verification attempts where certain elements were missing or the quality of the submission was subpar, a new attempt is generated and made available through the same session URL. It is important to use the same session URL for verification attempts made by the same end-user.

The default callbackURL (the address of the page where the end-user is sent after they have completed the verification flow) can be different depending on your integration. It is visible in Veriff Customer Portal > All Integrations > Integration name > Settings tab. For example: for all test integrations it is “https://www.veriff.com/get-verified?navigation=slim”.

You can overwrite the callbackURL for the:

• integration: change it in Veriff Customer Portal > Integration’s Settings tab

• session: define a new URL on session creation with POST /sessions request, in verification.callback field

Note: changing the value via API call will overwrite the default callback URL, but it will not change the callback URL that is visible in the Veriff Customer Portal. You can find the current value in the POST /sessions response payload, in verification.callback.

Also referred to as the redirect URL.

Note that there is a maximum limit to how many sessions you can create in an integration:

• Enterprise customer: 600 sessions per minute

• Self-Serve customer: 30 sessions per minute

It is a session-specific token for a verification session: a JSON Web Token (JWT) that consists of the session ID and the session creation timestamp. It should always have the variable max length type and must be able to accept data up to 8KB.

It is a legacy element, currently retained for backward compatibility.

You can find its value in the response payload of the POST /sessions, as verification.sessionToken.

Yes. Click on the three dots next to the API name and select “Download API reference”. That will save the API’s OAS in .json format to your device.

Yes, Veriff supports digital document PDF upload for Brazilian documents. This feature allows users to upload government-issued digital documents (Digital Driving Licenses and Digital National Identity Cards) in PDF format instead of taking photos with their device camera.

All PDFs are uploaded via POST /sessions/media API endpoint.

Supported Brazilian digital documents

• Digital Driving Licenses

• Digital National Identity Cards

Key benefits

• Market expectation compliance - many Brazilian users prefer uploading saved digital documents

• Enhanced security through SERPRO certificate signature validation

• Same data extraction capabilities as physical documents

• Fraud prevention through certificate validation

This feature is currently available only for Brazil and requires specific feature flags and decision profile configuration. The upload option is geo-IP restricted to Brazilian users. Contact your Solutions Engineer for info and configuration.

Brazilian CPF (Cadastro de Pessoas Físicas) validation is a registry check that validates individual taxpayer registry information against Brazil's government database. This solution requires that Brazilian taxpayer registry check is enabled for your integration. Contact your Solutions Engineer for info and configuration.

Information provided in decision webhook payload (additionalVerifiedDtata.cpfValidation object):

• status (string | null): Registry status: CPF is validated, CPF is suspended, CPF holder is deceased, CPF is pending regularization, CPF is cancelled (was a duplicate), or Cancelled craft (meaning that it was cancelled due to reasons other than being a duplicate)

• cpfNumber (string | null): The Brazilian individual taxpayer registry number

• name (string): Person's full name as registered in the CPF database

• dateOfBirth (string | null): Person's date of birth in YYYY-MM-DD format

• yearOfDeath (string | null): Year of death if applicable (YYYY-MM-DD format)

This validation helps verify that the provided CPF number exists in the official registry and provides demographic information for cross-referencing with document data.

Colombia registry validation verifies Colombian identity documents against official government registries. It supports both document verification (IDV) flow and API-only (non-IDV) flow. This solution requires that Colombia registry validation check is enabled for your integration. Contact your Solutions Engineer for info and configuration.

Information provided in decision webhook payload (additionalVerifiedData.registryValidation object):

• countryRegistry (string | null): Country of the registry (Colombia)

• registryName (string | null): Name of the specific registry used

• fullNameSimilarity (number | null): Percentage match between document name and registry name

• documentValid (boolean): Whether the document exists and is valid in the registry

• personIsAlive (boolean): Whether the person is confirmed alive based on multiple registry sources

Three main validation checks

1. Document validity - Verifies document number and first issue date

2. Person liveness - Confirms person is alive using 4-5 registry sources

3. Name matching - Compares full name similarity with configurable thresholds

This validation helps prevent fraud by confirming document authenticity against official Colombian government databases.