Veriff Getting Started Guide: Account, Keys, First Request (2026)

Getting started overview

Integrating with Veriff enables developers to embed identity verification, KYC, and AML screening into applications for various use cases, including customer onboarding and fraud prevention. The initial setup involves creating a Veriff account, obtaining API credentials, and making a test request to establish a verification session. Veriff's API is designed to manage the verification flow, from session creation to result retrieval.

The core process typically involves:

1. Account Creation: Registering for a Veriff account to access the Veriff Station dashboard and obtain API keys.
2. API Key Generation: Generating public and private API keys within the Veriff Station for authentication.
3. Session Creation: Sending an API request to Veriff's API to initiate a new verification session, providing user-specific data.
4. User Redirection: Directing the end-user to the URL provided by Veriff's API response, where they complete the identity verification process.
5. Webhook Configuration: Setting up webhooks to receive real-time updates on the verification status.
6. Result Retrieval: Fetching the final verification decision and data from Veriff once the process is complete.

Veriff provides SDKs for Web, iOS, and Android to streamline the client-side integration of the verification flow, abstracting away some of the direct API interactions. For server-side operations, direct API calls or server-side SDKs are used.

Create an account and get keys

To begin using Veriff, developers must first create an account and generate the necessary API keys. These keys are fundamental for authenticating all API requests to Veriff's services.

Account registration

Navigate to the Veriff homepage and sign up for an account. Veriff offers a Starter tier that includes limited verifications for testing and initial development. During the registration process, you will typically provide basic company and contact information.

Accessing Veriff Station

After successful registration, you will gain access to the Veriff Station, which serves as the administrative dashboard for managing your verifications, viewing analytics, and configuring API settings.

Generating API keys

Within the Veriff Station, locate the API settings or developer section. Here, you can generate your API keys. Veriff typically uses a pair of keys:

• Public API Key: Used for client-side operations, like initializing SDKs.
• Private API Key (API Secret): Used for server-side operations, such as creating verification sessions and retrieving results. This key must be kept confidential and never exposed in client-side code.

Ensure you record these keys securely, as they are essential for all authenticated API interactions. For detailed steps on key generation, refer to the Veriff API authentication documentation.

Your first request

The first programmatic interaction with Veriff typically involves creating a verification session. This is a server-side operation that uses your private API key.

Example: Creating a verification session (cURL)

This example demonstrates how to create a session using cURL. Replace YOUR_PRIVATE_API_KEY with your actual private API key from Veriff Station.

curl -X POST \
  https://magic.veriff.me/api/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-AUTH-CLIENT: YOUR_PRIVATE_API_KEY" \
  -d '{ 
    "verification": { 
      "callback": "https://your-app.com/veriff-webhook", 
      "vendorData": "unique-user-id-123", 
      "person": { 
        "firstName": "John", 
        "lastName": "Doe", 
        "idNumber": "123456789", 
        "dateOfBirth": "1990-01-01"
      },
      "document": {
        "type": "PASSPORT",
        "country": "US"
      }
    } 
  }'

Explanation of parameters:

• X-AUTH-CLIENT: Your private API key for authentication.
• callback: The URL where Veriff will send webhook notifications about the verification status. This is crucial for real-time updates.
• vendorData: A unique identifier for your user or transaction, which helps you link Veriff's verification to your internal systems.
• person: Optional, but recommended, personal details of the user being verified.
• document: Optional details about the expected document type and country.

Expected response

A successful request will return a JSON object similar to this:

{
  "status": "success",
  "verification": {
    "id": "some-unique-veriff-session-id",
    "url": "https://magic.veriff.me/v/some-unique-veriff-session-id",
    "host": "magic.veriff.me",
    "vendorData": "unique-user-id-123",
    "status": "created",
    "sessionToken": "long-session-token"
  }
}

The crucial part of this response is the url field. This URL is where you must redirect your end-user to complete the identity verification process with Veriff. You can also use the id field to reference this specific verification session later.

Handling the user flow

Once you receive the url, your application should redirect the end-user to this link. The user will then interact directly with Veriff's interface to upload documents, take selfies, and complete the verification steps. After the user completes the process, Veriff will send notifications to the callback URL you provided during session creation.

Common next steps

After successfully initiating a verification session and understanding the basic flow, consider these common next steps for a full integration:

• Implement Webhooks: Configure your server to receive and process Veriff webhooks. These provide real-time updates on the status of a verification (e.g., started, resubmission_requested, approved, declined). This is critical for automating your application's response to verification outcomes without polling the API.

• Integrate SDKs: For a more seamless user experience, integrate one of Veriff's client-side SDKs (Web, iOS, Android). Veriff's Web SDK documentation explains how to embed the verification flow directly into your web application, providing more control over the UI/UX and handling some of the redirect complexities.

• Retrieve Verification Decisions: After a verification is completed and you receive a webhook notification, you can use the Get Verification endpoint to retrieve the full details and final decision for a session. This allows you to integrate the verification results into your business logic.

• Error Handling and Retries: Implement robust error handling for API requests and consider retry mechanisms for transient network issues. Veriff's API reference details specific error codes and their meanings.

• Testing with Different Scenarios: Test your integration with various scenarios, including successful verifications, failed verifications, and cases where a resubmission is required. Veriff provides guidelines for testing your integration effectively.

• Security Best Practices: Review security best practices for handling API keys (e.g., environment variables, secret management) and protecting personal data. The OAuth 2.0 framework, while not directly implemented for basic API key authentication, offers general principles for secure API access.

Troubleshooting the first call

When making your first API call to Veriff, common issues can arise. Here's a guide to troubleshooting them:

• Authentication Errors (401 Unauthorized):

  • Issue: Your API key is incorrect or missing.
  • Solution: Double-check that the X-AUTH-CLIENT header contains your correct Private API Key. Ensure there are no leading or trailing spaces. Confirm you are using the Private API Key for server-side requests, not the Public Key.

• Bad Request Errors (400 Bad Request):

  • Issue: The request body is malformed, or required parameters are missing or invalid.
  • Solution: Verify that your JSON payload is syntactically correct. Check the Veriff API reference for session creation to ensure all mandatory fields are present and data types are correct (e.g., dateOfBirth in YYYY-MM-DD format).

• Forbidden Errors (403 Forbidden):

  • Issue: Your API key might not have the necessary permissions, or your account may have restrictions.
  • Solution: Review your account settings in Veriff Station. If you are on a free or trial tier, there might be limitations on certain features or API calls. Contact Veriff support if the issue persists after verifying your key and payload.

• Network Connectivity Issues:

  • Issue: Your server cannot reach Veriff's API endpoint.
  • Solution: Check your server's network configuration and firewall settings. Ensure that outbound requests to magic.veriff.me are not blocked. You can test connectivity with a simple ping magic.veriff.me or curl -v https://magic.veriff.me from your server.

• Callback URL Issues:

  • Issue: Webhooks are not being received, or the provided callback URL is unreachable.
  • Solution: Ensure your callback URL is publicly accessible and correctly configured to accept POST requests. Use a tool like ngrok for local development to expose your local environment for testing webhooks. Verify that your server logs show attempts to receive webhooks from Veriff.

• Missing url in Response:

  • Issue: The API call was successful, but the response does not contain the url field for user redirection.
  • Solution: This is highly unusual for a successful session creation. Re-examine the response structure to confirm the status is success. If the issue persists, review the Veriff API documentation for any updates or contact support.

Always consult the Veriff API error code documentation for specific details on error responses.