Retrieve Credentials

Before running the application, set up some environment variables:

• Visit Didit Business Console (opens in a new tab) to obtain your CLIENT_ID, CLIENT_SECRET, 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:

  CLIENT_ID=<YourClientId>
  CLIENT_SECRET=<YourClientSecret>
  WEBHOOK_SECRET_KEY=<YourWebhookSecretKey>

Client Authentication

To call the Verification endpoints, provide the client access_token in the Authorization header as Bearer ${access_token}.

Refer to the Client Authentication section for detailed information and code examples.

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

Creating Verification Session

After obtaining a valid client access_token, call the verification service /v2/session/ endpoint with your selected workflow.

POST /v2/session/
Host: verification.didit.me
Content-Type: application/json
Authorization: Bearer {access_token}
 
{
  "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": "john.doe@example.com",
    "email_lang": "en",
    "phone": "+14155552671"
  }
}

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

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"
}

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.

(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
Authorization: Bearer {access_token}

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.