ID
Proval
Get started

Documentation

Build with
IDProval.

Type-safe SDKs, signed webhooks, and scoped API keys. 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: 'production',
});

// 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, create an API key, and run your first verification.

01

Install

Add the SDK

Node and TypeScript have a first-party client. Everywhere else, call the REST API directly. 

# NOT YET PUBLISHED. This 404s today. Read /docs/quickstart
# before running it, and check the publisher if it resolves.
npm install @id-proval/sdk
02

Authenticate

Set your API key

Secrets look like proval_sk_… and are shown once, at creation time. 

# .env
IDPROVAL_API_SECRET=proval_sk_...
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.

One first-party client today, @id-proval/sdk for TypeScript and Node, and it is not on the public npm registry yet. Every other language talks to the REST API directly, which is the same surface the SDK uses. We publish nothing on PyPI, Packagist, crates.io or the Go module proxy, so a package that claims to be ours is not ours.

TypeScript / Node.js

Type-safe SDK with full IDE autocomplete. Server and client entry points. Not on the public npm registry yet, so take it from the source we give you.

# not published yet, this 404s
npm install @id-proval/sdk

Python

No first-party package yet. Call the REST API with requests. We publish nothing on PyPI, so treat any package claiming to be ours as hostile.

pip install requests

Go

No first-party module yet. net/http and encoding/json are enough. We publish no Go module, so do not go get one that claims to be ours.

import "net/http"

REST API

Plain HTTP and JSON. Use any language. Bearer auth on every call.

curl https://idproval.com/api/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/{verification_id}

Retrieve a verification by ID

GET/v1/verifications

List verifications with pagination

KYC Sessions

Full KYC onboarding sessions: document, face match, and liveness with a reviewer queue for edge cases.

POST/v1/kyc

Create a new KYC session

GET/v1/kyc/{kyc_id}

Retrieve a KYC session by ID

GET/v1/kyc

List KYC sessions with pagination

Document OCR

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

POST/v1/document/{type}

Extract fields from a document (MRZ + visual zone)

POST/v1/extract/document

General document text extraction

GET/v1/document-schemas/{country}/{doc_type}

Fields available for a country and document type

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

POST/v1/age/compare

Compare an estimated age against a threshold

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/liveness/challenge/{challenge_type}

Issue a liveness challenge

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.

01

Quickstart

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

Read guide
02

Authentication

API keys, scopes, IP allowlists, expiry, and key rotation.

Read guide
03

Webhooks

Signed payloads, the retry schedule, and how to verify a signature.

Read guide
04

Errors

Status codes, error shape, and a retry strategy that will not double-charge you.

Read guide
05

Production

Pre-flight checklist before you put real users through the flow.

Read guide
06

Age verification modal

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

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. Failed deliveries are retried with backoff until they succeed.

  • 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