Identity Verification Endpoints

The Leypal Identity Verification API lets you initiate document-based identity checks for your users and retrieve the results. Use these endpoints to verify that a person is who they claim to be before allowing them to sign sensitive documents.

Workflow overview:

Initiate a verification — the API returns a hosted session URL you redirect the user to
User completes the verification on Leypal's hosted flow (document upload, liveness check)
Receive a webhook (identity_verification.completed or identity_verification.failed) when the result is ready
Retrieve the result using the document report endpoint

Required scopes: identity:write to initiate verifications. identity:read to retrieve status and results.

Initiate Identity Verification

POST /api/v1/identity-verifications

Start a new identity verification process for a user. Returns a verification object including a sessionUrl to redirect the user to.

Full URL: https://api.leypal.dev/api/v1/identity-verifications

Request Body

Parameter	Type	Required	Description
`email`	string	Yes	Email address of the person being verified
`firstName`	string	Yes	First name of the person being verified
`lastName`	string	Yes	Last name of the person being verified
`documentType`	enum	Yes	Type of identity document: `passport`, `id_card`, or `drivers_license`
`verificationMethod`	enum	Yes	Verification approach: `document` (document scan only), `liveness` (selfie match), or `combined` (document + liveness)
`redirectUrl`	string	No	URL to redirect the user to after completing the verification flow
`metadata`	object	No	Arbitrary key-value pairs to attach to the verification for your own tracking

curl Example

curl -X POST https://api.leypal.dev/api/v1/identity-verifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "documentType": "passport",
    "verificationMethod": "combined",
    "redirectUrl": "https://yourapp.com/verification-complete"
  }'

Response — 201 Created

{
  "id": 1042,
  "email": "jane.doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "documentType": "passport",
  "verificationMethod": "combined",
  "status": "pending",
  "sessionUrl": "https://verify.leypal.dev/session/tok_9f8e2a1c4b6d",
  "redirectUrl": "https://yourapp.com/verification-complete",
  "metadata": {},
  "createdAt": "2026-03-30T10:00:00.000Z",
  "expiresAt": "2026-03-30T11:00:00.000Z"
}

Redirect the user to the sessionUrl immediately after creation. Sessions expire after 60 minutes. Once expired, you must create a new verification.

List Identity Verifications

GET /api/v1/identity-verifications

Retrieve a paginated list of all identity verifications for your organization.

Full URL: https://api.leypal.dev/api/v1/identity-verifications

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number, starting at 1 (default: 1)
`limit`	number	No	Results per page, max 100 (default: 20)
`status`	enum	No	Filter by status: `pending`, `in_progress`, `completed`, `failed`, `expired`

curl Example

curl -X GET "https://api.leypal.dev/api/v1/identity-verifications?page=1&limit=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "items": [
    {
      "id": 1042,
      "email": "jane.doe@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "documentType": "passport",
      "verificationMethod": "combined",
      "status": "completed",
      "createdAt": "2026-03-30T10:00:00.000Z",
      "updatedAt": "2026-03-30T10:18:34.000Z"
    },
    {
      "id": 1041,
      "email": "john.smith@example.com",
      "firstName": "John",
      "lastName": "Smith",
      "documentType": "id_card",
      "verificationMethod": "document",
      "status": "completed",
      "createdAt": "2026-03-29T14:22:00.000Z",
      "updatedAt": "2026-03-29T14:35:10.000Z"
    }
  ],
  "total": 47,
  "page": 1,
  "limit": 20
}

Get Identity Verification

GET /api/v1/identity-verifications/{verificationId}

Retrieve a single identity verification by its ID, including the full event history and current status.

Full URL: https://api.leypal.dev/api/v1/identity-verifications/{verificationId}

Path Parameters

Parameter	Type	Required	Description
`verificationId`	number	Yes	The numeric ID of the identity verification

curl Example

curl -X GET https://api.leypal.dev/api/v1/identity-verifications/1042 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "id": 1042,
  "email": "jane.doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "documentType": "passport",
  "verificationMethod": "combined",
  "status": "completed",
  "sessionUrl": null,
  "redirectUrl": "https://yourapp.com/verification-complete",
  "metadata": {},
  "createdAt": "2026-03-30T10:00:00.000Z",
  "updatedAt": "2026-03-30T10:18:34.000Z",
  "expiresAt": "2026-03-30T11:00:00.000Z",
  "events": [
    {
      "id": 301,
      "type": "identity_verification.created",
      "createdAt": "2026-03-30T10:00:00.000Z"
    },
    {
      "id": 302,
      "type": "identity_verification.started",
      "createdAt": "2026-03-30T10:05:12.000Z"
    },
    {
      "id": 303,
      "type": "identity_verification.document_uploaded",
      "createdAt": "2026-03-30T10:12:47.000Z"
    },
    {
      "id": 304,
      "type": "identity_verification.completed",
      "createdAt": "2026-03-30T10:18:34.000Z"
    }
  ]
}

Status values:

Status	Description
`pending`	Verification created, user has not yet started
`in_progress`	User has opened the session and is completing steps
`completed`	All verification steps passed — result available
`failed`	Verification could not be completed (document rejected, liveness failed)
`expired`	Session expired before user completed the flow

Get Verification Document Report

GET /api/v1/identity-verifications/{verificationId}/document-report

Retrieve the detailed verification result including document extracted data, match score, and the final outcome. Only available when status is completed or failed.

Full URL: https://api.leypal.dev/api/v1/identity-verifications/{verificationId}/document-report

Path Parameters

Parameter	Type	Required	Description
`verificationId`	number	Yes	The numeric ID of the identity verification

curl Example

curl -X GET https://api.leypal.dev/api/v1/identity-verifications/1042/document-report \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "verificationId": 1042,
  "result": "approved",
  "documentType": "passport",
  "matchScore": 0.97,
  "extractedData": {
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1990-06-15",
    "documentNumber": "P1234567A",
    "expiryDate": "2031-06-14",
    "nationality": "MX",
    "issuingCountry": "MEX"
  },
  "livenessResult": {
    "passed": true,
    "score": 0.99,
    "spoofDetected": false
  },
  "completedAt": "2026-03-30T10:18:34.000Z"
}

Result values:

Result	Description
`approved`	Document is genuine and the person matches — verification passed
`rejected`	Document could not be verified or liveness check failed
`manual_review`	Result is ambiguous — queued for human review (result available within 24h)

Note: The livenessResult field is only present when verificationMethod is liveness or combined. For document-only verifications, this field is null.

Note: Calling this endpoint when status is pending or in_progress returns a 404 Not Found error — the report is not generated until the verification is complete.

Identity Verification Endpoints

On this page