Sumsub Getting Started Guide: Account Setup & First API Call (2026)

Getting started overview

Integrating with Sumsub involves a series of steps designed to enable identity verification, AML screening, and fraud prevention within an application. The process typically begins with account creation and obtaining API credentials. Developers then configure their environment, either by using one of Sumsub's provided Software Development Kits (SDKs) or by directly interacting with the REST API. The initial objective is often to successfully submit an applicant for verification and retrieve its status.

Sumsub provides a Free Starter Plan for developers to explore the platform's core functionalities before committing to a paid plan. This allows for testing the integration flow and understanding the API's behavior without incurring costs. Comprehensive documentation, including an API reference and SDK guides, supports the integration process, offering examples in several programming languages such as Python, Node.js, and Java.

The typical path for a new integration is as follows:

1. Account Creation: Register for a Sumsub account, preferably a developer or free tier account.
2. Credential Retrieval: Obtain the necessary API keys and secrets from the Sumsub dashboard.
3. Environment Setup: Choose an integration method (SDK or direct API) and set up the development environment.
4. First Request: Execute a basic API call, such as creating an applicant or generating an access token.
5. Testing and Iteration: Verify the success of the initial call and proceed with further integration steps.

The table below summarizes these initial steps:

Create an account and get keys

To begin using Sumsub, you must first create an account. Sumsub offers a Free Starter Plan which allows access to core features for testing and development. Visit the Sumsub website and follow the registration prompts to set up your account. During registration, you will typically be asked for basic company information and contact details.

Once your account is active and you've logged into the Sumsub dashboard, the next critical step is to retrieve your API credentials. These credentials consist of an App Token (also referred to as API Key) and an Secret Key (or API Secret). These keys are essential for authenticating your requests to the Sumsub API, ensuring that only authorized applications can interact with your Sumsub instance.

To locate your API keys:

1. Log in to your Sumsub dashboard.
2. Navigate to the Integration section.
3. Select API keys.
4. Here you will find your App Token and Secret Key. It is crucial to treat your Secret Key as sensitive information, similar to a password. Do not expose it in client-side code or public repositories.

Sumsub's authentication mechanism typically relies on HMAC-SHA256 signatures for securing requests. When making an API call, you will use your App Token in the request header or URL, and the Secret Key to generate a signature for the request body and URL. This signature verifies the integrity and authenticity of the request. For detailed instructions on generating signatures, refer to the Sumsub API authentication guide.

For development purposes, Sumsub also provides a sandbox environment. This environment allows you to test your integration without affecting live data or consuming production quotas. The API keys generated in the dashboard are typically configured for either the sandbox or production environment, depending on your account setup and the specific key you generate. Always verify which environment your keys are linked to before making requests.

Your first request

After obtaining your API keys, the next step is to make your first API call to Sumsub. A common initial request is to create an applicant, which is the foundational object for any verification process. This typically involves sending a POST request to the /resources/applicants endpoint.

Before making the request, ensure you have a method to generate the required HMAC-SHA256 signature using your Secret Key. Many developers opt to use one of Sumsub's official SDKs, which abstract away the complexity of signature generation and HTTP request handling. Sumsub provides SDKs for Web (JavaScript), Android, iOS, Flutter, and React Native, as well as server-side libraries in Python, Node.js, PHP, Ruby, Java, and C#.

Example using Node.js (without SDK)

This example demonstrates how to create an applicant using Node.js and the axios library, manually handling the HMAC signature generation. Replace YOUR_APP_TOKEN and YOUR_SECRET_KEY with your actual credentials.

const axios = require('axios');
const crypto = require('crypto');

const APP_TOKEN = 'YOUR_APP_TOKEN';
const SECRET_KEY = 'YOUR_SECRET_KEY';
const BASE_URL = 'https://api.sumsub.com'; // Use https://api.sumsub.com for production, check docs for sandbox URL

async function createApplicant() {
  const path = '/resources/applicants';
  const method = 'POST';
  const timestamp = Math.floor(Date.now() / 1000);

  const body = {
    externalUserId: `some-user-id-${timestamp}`,
    firstName: 'John',
    lastName: 'Doe',
    email: `john.doe.${timestamp}@example.com`,
    // Add other relevant applicant data as per Sumsub documentation
  };

  const bodyString = JSON.stringify(body);

  const signatureString = timestamp + method + path + bodyString;
  const signature = crypto.createHmac('sha256', SECRET_KEY)
                          .update(signatureString)
                          .digest('hex');

  try {
    const response = await axios({
      method: method,
      url: `${BASE_URL}${path}`,
      headers: {
        'X-App-Token': APP_TOKEN,
        'X-App-Access-Sig': signature,
        'X-App-Access-Ts': timestamp,
        'Content-Type': 'application/json',
      },
      data: body,
    });

    console.log('Applicant created successfully:', response.data);
    return response.data;
  } catch (error) {
    if (error.response) {
      console.error('Error creating applicant:', error.response.data);
    } else {
      console.error('Error creating applicant:', error.message);
    }
    throw error;
  }
}

createApplicant();

This code snippet constructs a request to create an applicant. The externalUserId is a unique identifier from your system, crucial for tracking applicants. The timestamp and signature headers are vital for authentication. A successful response will contain details about the newly created applicant, including a sumsubId.

For a more detailed explanation of specific API endpoints and their required parameters, consult the Sumsub API reference for creating an applicant.

Common next steps

Once you have successfully made your first API call and created an applicant, several common next steps typically follow in a Sumsub integration:

1. Generate an Access Token: To integrate the Web SDK or mobile SDKs, you'll need to generate an access token for the created applicant. This token grants temporary, secure access to the Sumsub client-side components without exposing your API keys. The endpoint for this is POST /resources/accessTokens. The token typically has a limited lifespan and should be generated server-side and passed securely to your client application. Learn more about generating Sumsub access tokens.

2. Integrate the Web/Mobile SDK: With an access token, you can integrate Sumsub's client-side SDKs. These SDKs provide the user interface for document upload, liveness detection, and other verification steps, offering a streamlined user experience. The SDKs handle the complexities of camera access, image processing, and secure submission of data to Sumsub. For example, the Web SDK documentation provides detailed instructions on embedding the verification flow into your web application.

3. Set up Webhooks: Rather than continuously polling the Sumsub API for status updates, it is more efficient and reliable to configure webhooks. Webhooks allow Sumsub to send real-time notifications to your system when an applicant's status changes (e.g., approved, declined, pending review). This enables your application to react promptly to verification outcomes. Ensure your webhook endpoint is secure and can verify incoming requests to prevent spoofing, as outlined in Sumsub's webhook security guide.

4. Handle Applicant Statuses: Your application needs to implement logic to process the various applicant statuses returned by Sumsub. This includes approved, declined, pending, and various failure states. Proper handling ensures a smooth user experience and compliance with regulatory requirements. For example, a declined status might trigger an email notification to the user requesting additional information.

5. Configure Review Workflows: Sumsub allows for customization of review workflows, including setting up automatic approvals, manual review queues, and specific rules based on risk assessment. Tailoring these workflows to your business needs can optimize the balance between user experience and compliance. Explore the Sumsub review workflow documentation for configuration options.

6. Explore Additional Features: Depending on your use case, you might need to integrate additional Sumsub features such as KYB (Know Your Business) for corporate clients, AML (Anti-Money Laundering) screening, or advanced fraud prevention tools. Each of these features has specific API endpoints and integration patterns detailed in the main Sumsub documentation.

7. Monitor and Report: Implement monitoring for your Sumsub integration to track verification success rates, identify common issues, and monitor performance. The Sumsub dashboard provides analytics and reporting tools to help with this, but integrating these metrics into your internal monitoring systems can offer a more holistic view. For general best practices in API monitoring and observability, resources like Cloudflare's API monitoring overview can be helpful.

Troubleshooting the first call

When making your first API call to Sumsub, you might encounter issues. Here are common problems and their solutions:

• 401 Unauthorized / Invalid Signature: This is the most frequent issue. Double-check the following:

  • App Token: Ensure your X-App-Token header exactly matches the App Token from your dashboard.
  • Secret Key: Verify that the Secret Key used for generating the HMAC signature is correct. Copy-pasting errors are common.
  • Signature Generation: The HMAC-SHA256 signature must be generated precisely according to Sumsub's specifications. This includes the order of elements (timestamp, method, path, body) and the correct encoding. Refer to the Sumsub authentication guide for specific details.
  • Timestamp: The X-App-Access-Ts timestamp must be in Unix epoch seconds and reasonably close to the server's time (typically within a few minutes). Time synchronization issues on your local machine can cause this.
  • Request Body: If you are sending a request body (e.g., for POST requests), ensure it is included in the signature calculation exactly as it is sent in the request. Any discrepancy will invalidate the signature.

• 400 Bad Request: This usually indicates an issue with the request payload itself.

  • JSON Format: Ensure your request body is valid JSON. Use a JSON linter or validator.
  • Required Fields: Check if all mandatory fields for the specific endpoint (e.g., externalUserId for creating an applicant) are present and correctly formatted. Consult the Sumsub API reference for the endpoint you are calling.
  • Data Types: Verify that the data types for each field match the API's expectations (e.g., a string where a number is expected).

• 403 Forbidden: While less common for a first call with valid credentials, this can occur if your API keys lack the necessary permissions for the requested operation. Check your Sumsub account settings or contact support if you suspect a permission issue.

• Network Issues / Timeout: Ensure your server or development environment has proper internet connectivity and can reach api.sumsub.com. Firewall rules or proxy settings might interfere with the connection.

• Using the Wrong Base URL: Sumsub typically has different base URLs for sandbox (testing) and production environments. Ensure you are using the correct one for your API keys. The example above uses https://api.sumsub.com, which is typically for production; a sandbox URL would be different.

When troubleshooting, use detailed logging to capture the exact request (headers, body, URL) and the full response (status code, headers, body). This information is invaluable for diagnosing issues and for providing to Sumsub support if you need further assistance.