API Reference
Didit Console
Start typing to search…

API Full Flow

The Didit Identity Verification API operates through a workflow-based mechanism involving several steps outlined below.

Step 1: Retrieve Credentials

Before running the application, set up some environment variables:

  • Visit Didit Business Console to obtain your API_KEY, and WEBHOOK_SECRET_KEY for handling webhooks.
  • Configure WEBHOOK_URL in the application's advanced settings. For development purposes, you might use:
WEBHOOK_URL=https://yourapp.com/api/webhook
  • In your .env file, fill in the environment variables obtained from the step above. Your .env file will look something like this:
API_KEY=<YourApiKey>
WEBHOOK_SECRET_KEY=<YourWebhookSecretKey>

Step 2: Select Appropriate Workflow

Didit offers verification workflows through our workflow builder, allowing you to create tailored verification experiences.

Custom Workflow Builder

You can create a custom workflow starting with one of four base options:

  • KYC: Start with ID verification and add additional security layers
  • Adaptive Age Verification: Verify user age through facial analysis with optional ID verification
  • Biometric Authentication: Re-verify returning users who have previously completed verification
  • Address Verification: Verify user's residential address with optional additional verifications

Each workflow type can be enhanced with features like:

  • NFC verification
  • Liveness detection
  • Face matching
  • Phone verification
  • AML screening
  • IP analysis
  • And more

📘

Visit the Workflows page for detailed information on creating custom verification flows tailored to your specific needs.

Step 3: Creating Verification Session

Call the verification service /v2/session/ endpoint with your selected workflow.

POST /v2/session/
Host: verification.didit.me
Content-Type: application/json
X-Api-Key: {YourApiKey}

{
  "workflow_id": "11111111-2222-3333-4444-555555555555",  // Replace with your chosen workflow
  "callback": "https://example.com/verification/callback",
  "vendor_data": "user-123",  // Your user identifier
  "metadata": {
  	"user_type": "premium",
  	"account_id": "ABC123"
  },
  "contact_details": {
  	"email": "[email protected]",
  	"email_lang": "en",
  	"phone": "+14155552671"
  }
}

Refer to the Create Session section for detailed information and code examples.

Step 4: Handle Session Response

The response includes a URL to direct the user to:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "vendor_data": "user-123",
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "status": "Not Started",
  "workflow_id": "example_workflow_id",
  "callback": "https://example.com/verification/callback",
  "url": "https://verify.didit.me/session/abcdef123456"
}

Step 5: Obtain the results

Webhook for Verification Status

Webhooks are used to keep you notified of any status changes for the verification sessions you have created.

The webhooks are sent to the webhook URL configured on the business dashboard. To ensure that the webhook is from Didit, you need to verify the signature sent in the x-signature field of the header using the webhook secret obtained from the business dashboard.

The webhook payload includes the workflow_id field so you can apply appropriate business logic based on the workflow type.

Refer to the Webhooks section for detailed information and code examples on how to handle webhooks and verify their signatures.

Step 6: (Optional) Retrieving Verification Results through API

If you want to fetch verification results through the API, you can do so by calling the /v2/session/{sessionId}/decision/ endpoint. The recommended way of receiving verification results is through webhooks (step 5).

GET /v2/session/{sessionId}/decision/
Host: verification.didit.me
X-Api-Key: {YourApiKey}

The response structure varies based on the workflow used for the session, containing only the relevant feature components.

Refer to the Retrieve Session section for detailed information and code examples.

Integration Patterns

Web App Integration

For Web App workflows, the integration follows these steps:

  1. Customize the workflow in the Business Console
  2. Create a session with your selected workflow
  3. Redirect the user to the provided URL
  4. Wait for webhook notifications as the user progresses
  5. Apply your business logic when the verification is complete