Create an Identity Verification

Creating an identity verification involves 3 simple steps:

1. Create verification — send the user's data
2. User completes verification — accesses the link sent via email
3. Redirect to callback — user is redirected to your application with the result

Step 1: Create Identity Verification

Create a new identity verification that returns an id, a unique token, and an initial status.

curl --location 'https://api.leypal.com/api/v1/identity-verifications' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: sk_abc123xyz...' \
  --data '{
    "name": "John Doe",
    "email": "john.doe@example.com",
    "callbackUrl": "https://yourdomain.com/verify-callback"
  }'

Response:

{
  "id": 52,
  "email": "john.doe@example.com",
  "status": "pending",
  "expiresAt": "2026-04-07T14:34:53.337Z",
  "token": "8e4af0321d54480f54b61652cbfe1cbc1c7ff6b7227c2b327b999f7c4059c85e"
}

Save the id and token — you'll need them for future reference.

Required fields:

Step 2: User Completes Verification

Leypal will send an email to the user with a unique verification link. The user accesses the link and:

1. Uploads the front of their ID document
2. Uploads the back of their ID document (if needed)
3. Performs a liveness check (selfie)

The process is fully guided and asynchronous. Leypal will process the documents automatically using its verification pipeline.

Step 3: Redirect to Callback

Once the user completes the verification process (or cancels it), they will be redirected to your callbackUrl with query parameters:

https://yourdomain.com/verify-callback?sessionId=abc123&status=approved

Query parameters:

Final statuses:

• approved — Verification completed successfully
• failed — Verification failed (invalid documents, insufficient quality, etc.)

Next Steps

• Webhook Event Reference — Receive real-time notifications when verification status changes
• API Overview — Learn about authentication and limits