--- title: "Veriff API Documentation and API Reference" slug: "veriff-public-api-guides" description: "Integrate Veriff's Public API for seamless user verification, manage API keys, and enhance security with shared secret key rotation." tags: ["Veriff API"] status: "update" updated: 2026-09-03T14:10:22Z published: 2026-09-03T14:10:32Z canonical: "devdocs.veriff.com/veriff-public-api-guides" --- > ## 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. # Veriff API Documentation and API Reference > [!TIP] > Veriff Public API v1 There are a few scenarios where you may not wish to use Veriff's native or web SDKs to verify your end-users. For example: - You wish to completely implement your own front-end - You plan to collect end-users' media yourself - You wish to do an offline bulk audit of previously verified end-users In those cases, you can do the whole process using our API and you will not show any Veriff front-end to your end-users. --- ## Prerequisites In order to start sending media over the API, make sure that you: - [Created the integration](https://veriff-dev-documentation.document360.io/docs/how-to-create-an-integration)[↗] in the Veriff environment - [Configured the webhooks](https://veriff-dev-documentation.document360.io/docs/webhooks-guide)[↗] - Have all the necessary API key, API URL and headers at hand - Make sure you are familiar with Backwards compatible changes and ensure that you systems can handle these - You are ready to generate a verification session with [POST /sessions](https://veriff-dev-documentation.document360.io/apidocs/v1sessions) --- ![API integration settings with highlighted API keys and base URL for verification.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/API%20Keys%20tab_all%20sections.jpg) ## API keys Your Veriff integration uses two credentials: an API key and a shared secret key. You retrieve both from the Veriff Customer Portal. 1. **Log in** to Veriff Customer Portal via the link in your sign-up email (Enterprise customer) or you access link (Self-Serve Customer) 2. Navigate to **Workspace** > **All Integrations** page via left navigation bar 3. Open the integration you need 4. **API Keys** page opens, there you see: 1. The **API key**, used to create the X-AUTH-CLIENT header 2. The **shared secret key**, used to create the X-HMAC-SIGNATURE header ![](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/Vff%20Customer%20Portal_API%20Keys%20tab.jpg) ### Shared secret key #### One-time view > [!WARNING] > Your shared secret key is **shown only once,** at the time of creation. **Copy it immediately and store it securely**, Veriff does not store the secret value and it cannot be retrieved later. If you **lose it, revoke the key and create a new** one. Treat your shared secret key like a password: - Never share it with unauthorized parties. - Never commit it to source control. Each integration can have up to 5 shared secret keys. Each integration will also have an auto-generated key. It is possible to **view it at any time, but only once**. Creating and managing keys requires Admin permissions. #### Create a new shared secret key 1. **Log in** to the Veriff Customer Portal 2. Navigate to **Workspace** > **All Integrations page** via left navigation bar 3. Find and open the relevant integration 4. **API Keys** page opens 5. Navigate to **Shared secret keys** section 6. You can add a shared secret key using the **+ Add key** button and following the wizard 1. During the process, be ready to copy the newly created shared secret key into your secrets storage as it will be shown only once. 7. You can see all other keys available for this integration using the **See all keys** dropdown ![Display of shared secret keys with an option to add a new key.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/Add%20Key%20button(1).jpg) ![Creating a shared secret key with a descriptive name for integration purposes.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/add%20key%20dialog.jpg) ![Important message about your shared secret key and its one-time visibility.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/Shared%20key%20dialog.jpg) #### Master signature key > [!WARNING] > One shared secret key is designated the **master signature key**. Veriff uses this key to **sign all outgoing webhook events**. **API responses** are signed **using the key that was active when the original request was made**. Only one key can hold master status at a time. #### Rotate a shared secret key Veriff recommends rotating shared secret keys at least once a year. Follow the steps below to rotate without interrupting your webhook flow. > [!CAUTION] > If you delete the master signature key before promoting a replacement, webhook signature verification will fail immediately for all incoming Veriff events. Complete all steps in order before deleting any key. To rotate the keys: 1. On the **API Keys** page, use the **+ Add key** button. Copy and store the new shared secret immediately. 2. Update your webhook signature verification code to use the new shared secret. 3. Deploy and confirm the updated code is live and processing webhooks correctly. 4. Use the **three dots** next to a key to s**et it as master signature key** 5. Confirm that webhooks are still being received and verified successfully. 6. Use the **three dots** next to a key to **delete** the key after confirming that everything works ![Display of shared secret keys with options to set a master signature key.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/Set%20as%20new%20master%20key.jpg) #### Delete a compromised key If a key is compromised, act immediately: 1. Create a new shared secret key and store it securely. 2. If the compromised key is the master, promote the new key to master before deleting. 3. Update your webhook signature verification code with the new secret and deploy. 4. Delete the compromised key. --- ## API URL Example: `https://<base-URL>/v1/` To create the API URL: 1. First, find your **BaseURL** from the **API Keys** page in **Veriff Customer Portal**. 2. Next, to create the `API URL`, add `v1` to the Base URL value Your API calls need to be sent to an URL which consists of the following elements: - API URL - path - contains one of: {sessionId} / {attemptId} / {mediaId} - if relevant, any query parameters Example: https://veriff.me.api/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/curp-registry?version=1.0.0 Check each endpoints’ documentation for exact info. --- ## API headers The example below shows basic `headers`. These are often needed to send requests, or are returned in responses: - `x-auth-client`: `string` (required) - Your integration's API key. Required to identify the request or response sender. - `x-hmac-signature`: `string` (required) - HMAC-SHA256 hex encoded keyed hash using your shared secret key. Required to authenticate the response sender. - `vrf-auth-client`: `string` (always sent in responses) - Your integration's API key. Required to identify the request or response sender. Same as `x-auth-client` header. - `vrf-hmac-signature`: `string` (always sent in responses) - HMAC-SHA256 hex encoded keyed hash using your shared secret key. Required to authenticate the response sender. Same as `x-hmac-signature`. - `content-type`: `string` (required for POST/PATCH calls) - Media type of the resource (application/json) - `vrf-integration-id`: `string` (always sent in responses) - an UUID identifying an integration (aka Integration ID --- ## Backwards compatible changes All the changes listed below are considered to be backwards compatible by Veriff. Make sure to set up your systems in such flexible manner that it is able to handle these changes. - Adding new properties (e.g., `strings`, `objects`, `arrays`) to existing API responses - Changing the order* of properties in existing API responses, i.e., the order of `strings`, `objects`, `arrays` - Adding new API resources, e.g., adding new API endpoints - Adding new optional request parameters to existing API endpoints - Changing the length or format of opaque** strings, such as error messages, object IDs, etc. - Adding new event types to webhooks - Adding new properties (e.g., `strings`, `objects`, `arrays`) to webhook payloads - Webhook listener should gracefully handle unfamiliar event types *As a general note on the order of properties in the responses, keep in mind that the order is not static. This means that the order you see in your API call responses may differ from the order you see in Veriff documentation. **This means data that your system should be able to just transmit or store, not interpret. --- ## Customers API flow in a nutshell ### Create a verification session The goal here is to create a new object (a verification session) that contains one verification, nested inside the session object in the response. Also, you will receive the session ID, which you need for the next step. ### Send end-user's media Using the session ID, pass the end-user's media (face, document front, document back, etc.) by uploading all images (and video if applicable) one by one using the POST request to [POST /sessions/{sessionId}/media](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidmedia-3) endpoint. The goal here is to upload the required photos and associate them with the verification created in step 1. ### Take advantage of the additional collected data In order to further improve the IDV process, we strongly recommend you collect some additional end-user data and send it to us via [POST sessions/{sessionid}/collected-data](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidcollected-data-1). This step is not mandatory, but it is highly recommended. ### Submit session for review Once all the media and additional data has been uploaded, you then submit the verification session by sending the PATCH request to [PATCH /sessions/{sessionId}](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsid-2) and marking the verification to submitted status. Make sure that all the media has been submitted prior to triggering the PATCH request. ### Wait for Veriff to verify the end-user After these three steps, you have done your part, and the verification will then be taken care of by us. ### Wait for webhook response Veriff sends different types of webhooks for different event types using the POST method. For all the solutions, you can choose to configure the optional [event webhook](https://devdocs.veriff.com/docs/event-webhook) [↗] to notify you about the progress of the verification flow (events). Veriff sends the [decision webhook](/v1/docs/decision-webhook) [↗] for the following solutions: - Identity and Document Verification ([doc + selfie](https://devdocs.veriff.com/docs/document-selfie-idv) and [doc-only](https://devdocs.veriff.com/docs/document-only-idv)) - [Biometric Authentication](https://devdocs.veriff.com/v1/docs/biometric-authentication) - [Biometric Liveness](https://devdocs.veriff.com/docs/biometric-liveness) - [Age Estimation](https://devdocs.veriff.com/docs/age-estimation) - [AML screening](https://devdocs.veriff.com/docs/aml-screening) - [UK DIATF](https://devdocs.veriff.com/docs/uk-diatf) - [Mexican INE Biometric Database Verification](https://devdocs.veriff.com/docs/ine-biometric-database-verification) It contains a payload with the verification session decision and some additional data, including the verified identity information. Veriff sends the [watchlist-screening webhook](https://devdocs.veriff.com/docs/watchlist-screening-webhook) [↗] for AML screening without IDV checks For specific Mexican registry checks Veriff sends: - [INE webhook](https://devdocs.veriff.com/docs/ine-webhook) [↗] - [CURP webhook](https://devdocs.veriff.com/docs/curp-webhook) [↗] - [Combined INE+CURP webhook](https://devdocs.veriff.com/docs/inecurp-webhook) [↗] Veriff sends the [user-defined statuses webhook](https://devdocs.veriff.com/docs/user-defined-statuses-webhook) [↗] for when user has added a status to an attempt in the Veriff Customer Portal. Veriff sends the [full auto webhook](https://devdocs.veriff.com/docs/full-auto-webhook) [↗] for Self-Serve Essential plan customers. --- ## Available endpoints and methods ### To guide the verification flow [POST /sessions](https://devdocs.veriff.com/apidocs/v1sessions) - **starts a verification session** [POST /sessions/{sessionId}/collected-data](https://devdocs.veriff.com/apidocs/v1sessionsidcollected-data-1) - allows **uploading the data collected by you**, using the `sessionId` [POST /sessions/{sessionId}/media](https://devdocs.veriff.com/apidocs/v1sessionsidmedia-3) - allows **uploading media for the session**, using the `sessionId` [PATCH /sessions/{sessionId}](https://devdocs.veriff.com/apidocs/v1sessionsid-2) - allows **updating the session status to “submitted”** to pass the session on to verification process, using the `sessionId` [POST /sessions/validate-registry](https://devdocs.veriff.com/apidocs/v1validate-registry) - creates a session and **validates a national ID number** with provided data [DELETE /sessions/{sessionId}](https://devdocs.veriff.com/apidocs/v1sessionsid-3) - allows **deleting the session**, useful when testing, using the `sessionId`. Not available by default. ### To query decision, media and other data from the verification session [GET /sessions/{sessionId}/decision](https://devdocs.veriff.com/apidocs/v1sessionsiddecision-1) - allows querying the **verification session decision data**, using the `sessionId` [GET /sessions/{sessionId}/person](https://devdocs.veriff.com/apidocs/v1sessionsidperson-1) - allows querying the **data related to the person** verified in the session, using the `sessionId` [GET /sessions/{sessionId}/watchlist-screening](https://devdocs.veriff.com/apidocs/v1sessionsidwatchlist-screening-1) - returns a list of **data objects from PEP and Sanctions** services [GET /sessions/{sessionId}/media](https://devdocs.veriff.com/apidocs/v1sessionsidmedia-2) - allows querying **info about the media** uploaded during the session (using the `sessionId`) [GET /sessions/{sessionId}/attempts](https://devdocs.veriff.com/apidocs/v1sessionsidattempts-1) - allows querying the **id-s of different attempts** done during one verification session, using the `sessionId` [GET /attempts/{attemptId}/media](https://devdocs.veriff.com/apidocs/v1attemptsidmedia-1) - allows querying **info about the media** uploaded during a certain attempt (using the `attemptId`) [GET /media/{mediaId}](https://devdocs.veriff.com/apidocs/v1mediaid-1) - allows querying the **media file** using the `mediaId` of a specific media file ### To get registry-specific data [GET /sessions/{sessionId}/decision/ine-registry](https://devdocs.veriff.com/apidocs/v1sessionsiddecisionine-registry-1) - allows querying **verification data from Mexican INE registry**, using the `sessionId` [GET /sessions/{sessionId}/decision/curp-registry](https://devdocs.veriff.com/apidocs/v1sessionsiddecisioncurp-registry-1) - allows querying **verification data** from **Mexican CURP registry**, using the `sessionId` [GET /sessions/{sessionId}/decision/combined-ine-curp-registry](https://devdocs.veriff.com/apidocs/v1sessionsiddecisioncombined-ine-curp-registry-1) - allows querying **verification data** from the **combined Mexican registries check**, using `sessionId` --- ## Article versioning | Date | Description | | --- | --- | | Sep 3, 2026 | Typo fixed | | Jun 4, 2026 | [API Keys](/v1-api/apidocs/veriff-public-api-guides#api-keys) section updated: new info about shared secret key one-time view and rotation steps | | Sep 15, 2025 | - Flexible API keys info removed - [API headers](/v1-api/apidocs/veriff-public-api-guides#api-headers) section updated | | Apr 7, 2025 | List of solutions in “Wait for webhook response” updated | | Mar 12, 2025 | Documentation published | A **unique identifier of an integration.** A **required parameter for authentication: i**t is used to create the `X-AUTH-CLIENT header` value for **API requests**. Occasionally, referred to as the "API public key" or "Publishable key". You can find it in **Veriff Customer Portal** > **API keys** page (you need to be logged in). An **address** that allows you to access an API and its various features. It consists of a `BaseURL` and an `endpoint`. Occasionally, also referred to as the "API URL path". **Mandatory elements** in the **API requests**, containing the metadata. A session during which the end-user is verified. It starts when a session is created, it can contain several attempts (i.e. steps of uploading media, sending additional data etc.) and it ends when a conclusive decision (“approved”, “declined”, “expired”/”abandoned”) is granted. Each verification session receives an unique ID, aka the **session ID**, which can be added to the API URL when making API requests. **Mandatory parameter for authentication**, used to **sign the payload to create the X-HMAC-SIGNATURE** for API requests. This is a **secret credential**. You can find it in **Veriff Customer Portal** > **Integration** tab (you need to be logged in). Occasionally, referred to as the "API private key" or the "Private key". 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**. An environment created according to customer's needs to carry out, manage and observe verifications. You can find the list of your integrations in **Veriff Customer Portal** > **All** **Integrations** page (you need to be logged in). A **mandatory header field** in API requests, **required to identify the request sender**. Its value is the **API key**. A **mandatory header** field in API requests, **required to authenticate the request sender**. Its value is a **HMAC-SHA256 hex encoded hashed value of the request payload** that has been **signed using a shared secret key** known to both the sending and receiving party. Each API requests documentation in the API Documentation specifies the payload to be encoded. For more info about the signature itself, see *Technical Guides* > *HMAC Authentication and Endpoint Security.* A "base address" for the specific API that you are using. **Used to create the API URL** value for API requests. You can find it in **Veriff Customer Portal** > **All** **Integrations >** *Integration name* **> API keys** tab (you need to be logged in). UUID identifying an integration. Sent as `vrf-integration-id` header in webhook and API responses. A **unique identifier of a verification session**. It is automatically created as soon as you create a session. In the **API requests' context**, one verification session comprises many steps (uploading data, uploading images, getting a decision, etc.). You can call several endpoints using the same **session ID**, to get all kinds of different data from that specific session. You can find its value in the **response payload** of your **POST /sessions API request**, in the `verification.id` parameter. A specific “point of entry” in an API. For **webhooks**, this is the point of entry on your side. For **Veriff public API**, you need to attach an endpoint to the end of your `baseURL` to complete the **API URL**. The results that you will get from the Veriff public API request will depend on the endpoint you attach. Abbreviation of **Identity Verification**. A **process where the end-user submits the data** required to get verified. Also referred to as the "end-user flow". In the API requests' context, an "attempt" is one step (uploading required data and getting a decision) inside a verification session, and it can be made several times during one verification session.