Onfido Getting Started: Account, Keys & First API Call (2026)

Getting started overview

Getting started with Onfido involves a sequence of steps to integrate its identity verification capabilities into an application. The process begins with account creation, followed by obtaining API credentials. Developers then proceed to make their first API call, which typically involves creating an Applicant and initiating an identity check. Onfido provides a REST API and client-side SDKs to facilitate this integration process (Onfido Developer Hub).

The primary goal for developers initiating integration with Onfido is to programmatically perform identity verification. This can include document verification, biometric checks, and watchlist screening, depending on the specific use case (Onfido Homepage). The initial setup focuses on establishing secure communication with the Onfido API and understanding the basic resource model.

Key integration components include:

• API Keys: For authenticating requests to the Onfido API.
• Applicants: The primary resource representing an individual undergoing verification.
• Documents: Files submitted by applicants for verification, such as passports or driver's licenses.
• Checks: The verification process initiated on an applicant's submitted data.
• Webhooks: For receiving asynchronous updates on the status of checks.

The following table outlines the foundational steps for integrating with Onfido:

Create an account and get keys

To begin using Onfido, you must first create an account. This provides access to the Onfido Dashboard, where you can manage your integrations, view checks, and retrieve API credentials. Accounts typically start with a free trial or a developer sandbox environment to facilitate initial testing and integration without incurring costs (Onfido Pricing Page). The signup process usually requires basic organizational and contact information.

Once your account is active, you will need to generate an API key. API keys serve as the primary method for authenticating your application's requests to the Onfido API. Onfido uses a token-based authentication scheme, where the API key is included in the Authorization header of each request. The specific format often follows the Bearer token standard, as outlined by RFC 6750 (IETF RFC 6750 Bearer Token Usage).

Steps to obtain API keys:

1. Log in to the Onfido Dashboard: Access your account through the Onfido website.
2. Navigate to API Keys: In the dashboard, locate the "Developers" or "API Keys" section.
3. Generate a New Key: Select the option to create a new API key. You may be prompted to name the key for organizational purposes.
4. Copy the Key: The generated API key will be displayed. It is crucial to copy this key immediately and store it securely, as it may only be shown once.

Onfido provides different environments, typically a Sandbox (test) environment and a Live (production) environment. Each environment will have its own set of API keys. It is recommended to use Sandbox keys for development and testing to prevent unintended charges or impacts on live data (Onfido Environments Guide).

Example of an API key in an HTTP header:

Authorization: Bearer YOUR_API_KEY_HERE

Protecting your API keys is critical. They should be treated as sensitive credentials and never hardcoded into client-side code, exposed in public repositories, or shared insecurely. Best practices include using environment variables, a secrets management service, or server-side proxying for API calls.

Your first request

After obtaining your API key, the next step is to make your first API call to Onfido. A common starting point is to create an Applicant resource. An Applicant represents the individual whose identity you intend to verify. This initial request confirms that your API key is correctly configured and that your application can communicate with the Onfido API.

Onfido's API is a RESTful API, meaning it adheres to principles like statelessness, client-server separation, and uniform interface, using standard HTTP methods (POST, GET, PUT, DELETE) and JSON for data exchange (Onfido API Reference).

Here's an example of how to create an Applicant using curl, a widely used command-line tool for making HTTP requests:

curl -X POST \ \
  https://api.onfido.com/v3.6/applicants \ \
  -H 'Authorization: Bearer YOUR_API_KEY' \ \
  -H 'Content-Type: application/json' \ \
  -d '{ \ \
    "first_name": "Jane", \ \
    "last_name": "Doe", \ \
    "email": "[email protected]" \ \
  }'

Replace YOUR_API_KEY with the actual API key you generated from your Onfido dashboard. If successful, the API will return a JSON response containing details of the newly created applicant, including a unique id. This id is crucial for subsequent API calls related to this applicant, such as uploading documents or initiating checks.

Example successful response:

{
  "id": "abc12345-def6-7890-1234-567890abcdef",
  "created_at": "2023-01-01T12:00:00Z",
  "href": "/v3.6/applicants/abc12345-def6-7890-1234-567890abcdef",
  "sandbox": true,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "dob": null,
  "address": null,
  "id_numbers": [],
  "phone_number": null,
  "motion_capture_from_sdk": false,
  "live_photos": []
}

This response confirms that you have successfully authenticated and interacted with the Onfido API. The id field from this response will be used in subsequent requests to associate documents and checks with this specific applicant.

Common next steps

After successfully creating an applicant, the typical progression involves submitting identity documents and initiating the verification process. Onfido offers various SDKs (iOS, Android, Web) that simplify the document and biometric capture process, providing a guided user experience and handling complexities like image quality and liveness detection (Onfido SDK Documentation).

1. Uploading Documents:

Once an applicant is created, you will need to upload their identity documents (e.g., passport, driver's license). This is done using the "Upload Document" endpoint, associating the document with the applicant's ID. The document typically needs to be sent as a multipart/form-data request.

Example curl for uploading a document:

curl -X POST \ \
  https://api.onfido.com/v3.6/documents \ \
  -H 'Authorization: Bearer YOUR_API_KEY' \ \
  -F 'applicant_id=abc12345-def6-7890-1234-567890abcdef' \ \
  -F 'type=passport' \ \
  -F 'side=front' \ \
  -F 'file=@/path/to/your/passport_front.jpg'

2. Creating a Check:

With documents uploaded, you can initiate a "Check" to perform the actual verification. A check defines what types of verification Onfido should perform (e.g., document, facial similarity, watchlist). The check references the applicant and optionally the documents or live photos submitted.

Example curl for creating a check:

curl -X POST \ \
  https://api.onfido.com/v3.6/checks \ \
  -H 'Authorization: Bearer YOUR_API_KEY' \ \
  -H 'Content-Type: application/json' \ \
  -d '{ \ \
    "applicant_id": "abc12345-def6-7890-1234-567890abcdef", \ \
    "report_names": ["document", "facial_similarity_photo"] \ \
  }'

After creating a check, its status will initially be in_progress. You can poll the "Retrieve Check" endpoint or, more efficiently, configure webhooks to receive asynchronous notifications when the check status changes to complete or awaiting_input (Onfido Webhook Guide).

3. Handling Webhooks:

Webhooks are essential for production environments as they provide real-time updates without constant polling. You configure a URL in your Onfido dashboard where Onfido will send POST requests whenever an event occurs (e.g., check completed, document uploaded). Implementing webhook security, such as verifying signatures, is crucial for ensuring the integrity and authenticity of incoming notifications (Stripe Webhook Signature Verification Guide).

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some frequent problems and their solutions:

• 401 Unauthorized:

  • Issue: This usually means your API key is invalid or missing in the Authorization header.
  • Solution: Double-check that you've correctly copied and pasted the API key from your Onfido dashboard. Ensure it's prefixed with Bearer and a space, and that there are no extra characters or missing parts. Verify you are using a Sandbox key for the Sandbox API endpoint, and a Live key for the Live API endpoint.

• 403 Forbidden:

  • Issue: Your API key might not have the necessary permissions for the requested action, or you might be trying to access a resource that doesn't belong to your account.
  • Solution: Review the permissions associated with your API key in the Onfido dashboard. If it's a fresh key, ensure it's not restricted. This can also occur if you're trying to access an applicant ID that was created under a different account or environment.

• 400 Bad Request:

  • Issue: The request body is malformed, or required parameters are missing or incorrect.
  • Solution: Carefully inspect your JSON payload for syntax errors (e.g., missing commas, unclosed brackets, incorrect data types). Refer to the Onfido API Reference for the exact schema required for the endpoint you are calling. For example, ensure first_name and last_name are strings and not null for applicant creation.

• 404 Not Found:

  • Issue: The endpoint URL is incorrect, or the resource you're trying to access (e.g., an applicant with a specific ID) does not exist.
  • Solution: Verify the API endpoint URL for typos. Ensure you are using the correct API version (e.g., v3.6). If you're trying to retrieve an applicant, double-check that the ID is correct and that the applicant was successfully created in the first place.

• Network Errors (Connection Refused, Timeout):

  • Issue: Your application cannot reach the Onfido API servers.
  • Solution: Check your internet connection. Ensure no firewalls or network configurations are blocking outgoing HTTPS requests to api.onfido.com. Temporal issues can sometimes be resolved by retrying the request.

• SDK-specific Issues:

  • Issue: Problems with integrating or using one of Onfido's client-side SDKs.
  • Solution: Consult the specific Onfido SDK documentation for iOS, Android, or Web. Ensure all dependencies are correctly installed and configured, and that you are following the SDK's initialization and flow guidelines.

For persistent issues, Onfido's developer documentation and support channels are valuable resources. Providing detailed error messages, request/response payloads, and steps to reproduce the issue will help in diagnosing the problem effectively.