ID
Proval
Get started

Documentation

Build with
IDProval.

Type-safe SDKs, signed webhooks, sandbox keys out of the box. Pick a guide, drop in a snippet, and have verification running in your app in an afternoon.

Quickstart API reference

5 min

first verify

4

SDKs

Signed

webhooks

verify.ts

import { createServerClient } from '@id-proval/sdk/server';

const client = createServerClient({
  apiSecret: process.env.IDPROVAL_API_SECRET,
  environment: 'sandbox',
});

// Create a verification session
const session = await client.verification.create({
  external_id: 'order_abc123',
});

return { url: session.url };

Quickstart

Three steps. Five minutes.

Sign up, grab a sandbox key, and run your first verification.

01

Install

Add the SDK

Pull in the official client for your language. Tree-shakeable, zero peer-dependency surprises. 

# npm
npm install @id-proval/sdk
02

Authenticate

Set your API key

Sandbox keys start with sk_test_. Production keys start with sk_live_. 

# .env
IDPROVAL_API_SECRET=sk_test_...
03

Verify

Create a session

One call returns a hosted URL. Redirect your user, and we'll send the verdict back via webhook. 

await client.verification
  .create({ external_id });

SDKs

Ship in your favourite language.

First-party clients, type-checked, semver-stable. Or hit the REST API directly from anything that speaks HTTP.

TypeScript / Node.js

Type-safe SDK with full IDE autocomplete. Server and client packages.

npm install @id-proval/sdk

Python

Python 3.10+ SDK. Sync and async clients with typed responses.

pip install idproval

Go

Idiomatic Go client. Context-aware, with structured error types.

go get github.com/idproval/idproval-go

REST API

Plain HTTP + JSON. Use any language. OpenAPI 3.1 spec available.

curl https://api.idproval.com/v1/...

API reference

Every endpoint, grouped by API.

The full surface area: verification flows, document OCR, age estimation, face match, and liveness.

Verification Flow

Hosted flow that orchestrates document scan, liveness, and age check. Returns a verdict via webhook.

POST/v1/verifications

Create a new verification session

GET/v1/verifications/{id}

Retrieve a verification by ID

GET/v1/verifications

List verifications with pagination

Document OCR

Synchronous passport extraction. Submit a passport image and get structured fields back.

POST/v1/document/passport

Extract fields from a passport (MRZ + visual zone)

Age Estimation

Passive age estimation from a single selfie. No document required for low-risk flows.

POST/v1/age/estimate

Estimate age from a face image

Face Match & Liveness

Compare a selfie against a document portrait, detect spoofs, and verify liveness.

POST/v1/face/match

Compare two face images

POST/v1/face/liveness

Run liveness check on a video or image

Age Requirements

Ask whether a visitor’s country legally requires age verification for your content type, so an age gate does not have to hardcode a country list that goes stale when a regulator moves.

GET/v1/age-requirements

Requirements for a country + purpose (min age, tier, accepted methods)

Digital Identity Wallet

Offer EU Digital Identity Wallet verification (OID4VP) inside a verification session. The user presents a signed credential instead of scanning a document.

POST/v1/verifications

Create a session and enable the wallet method in options

Guides

Everything else you'll need.

How to authenticate, handle webhooks, recover from errors, and roll out to production.

Age verification modal

Create a session, open the modal, and wire the result into your existing login.

Read guide

Quickstart

Sign up, get your API key, and run your first verification in under 5 minutes.

Read guide

Authentication

API keys, scopes, sandbox vs. production environments, and key rotation.

Read guide

Webhooks

Signed webhook payloads, retry policy, and how to verify the signature.

Read guide

Errors

Standard error codes, retry strategy, and how to handle rate limits.

Read guide

Sandbox

Test data, fixed verdicts, and trigger codes to test edge cases.

Read guide

Going to Production

Pre-flight checklist, KYB requirements, and live key activation.

Read guide

Webhooks

Verdicts arrive on your endpoint.

Every event is signed with HMAC-SHA256. Verify the signature, decode the payload, and update your record. Retried up to 8 times with exponential backoff.

  • HMAC-SHA256 signed
  • At-least-once delivery
  • Median latency under 800 ms

verification.completed

delivered 
{
  "id": "evt_01HX...",
  "type": "verification.completed",
  "created_at": "2026-05-06T10:32:14Z",
  "data": {
    "verification_id": "ver_01HX...",
    "external_id": "order_abc123",
    "verdict": "approved",
    "confidence": 0.97,
    "checks": {
      "document": "pass",
      "liveness": "pass",
      "face_match": "pass"
    }
  }
}

Need help?

Talk to a real engineer.

Stuck on an integration? We'll review your code, debug your webhook handler, and walk you through go-live.

Get started for free Contact support