Quickstart

Before you start

You need an IDProval account and an organization. If you don't have one, sign up. Creating an organization is part of onboarding.

There is no separate sandbox environment today, so the calls below run against live infrastructure and count towards your usage. Use a document and a face you are happy to put through a real verification while you are wiring things up.

1. Create an API key

In the dashboard, open Settings → API keys and create a key. Give it the write:sessions and read:sessions scopes, which is the minimum for creating a verification and reading the result.

The secret is shown once, at creation time. Copy it immediately; there is no way to retrieve it later, only to roll the key. Store it as an environment variable, never in client-side code or a committed file.

IDPROVAL_API_SECRET=proval_sk_…

Scopes, expiry and IP allowlists are covered in Authentication.

2. Install the SDK

There is one first-party SDK today, for TypeScript and Node. Everything else talks to the REST API, which is the same surface the SDK calls.

# TypeScript / Node.js # NOT YET PUBLISHED: this returns a 404 today. If it resolves, # check the publisher before running it. See the note below. npm install @id-proval/sdk # Every other language: plain HTTP, no package to install

@id-proval/sdk is the only package name we will ever ask you to install, and it is not on the public npm registry yet: the command above returns a 404 until we publish it. Until then, take the SDK from the source we hand you directly. If the name starts resolving before we have announced a release, check the publisher on npm before letting it near a process that holds your API secret.

We publish no Python, Go, PHP or Ruby package. This page used to tell you to run pip install idproval and go get github.com/idproval/idproval-go. Those names are not ours and were never registered, so following that instruction would have installed whatever a stranger uploaded under the name, inside a process holding your IDPROVAL_API_SECRET. If you ran it, treat the key as exposed and roll it. A package that claims to be the IDProval SDK and is not @id-proval/sdk on npm is not ours.

3. Create a verification session

Do this on your server. The call needs your API secret, so it can never happen in the browser. Pass your own identifier as external_id so you can match the result back to a user or order later.

import { createServerClient } from '@id-proval/sdk/server'; const client = createServerClient({ apiSecret: process.env.IDPROVAL_API_SECRET, environment: 'production', }); const session = await client.verification.create({ external_id: 'order_abc123', });

Or with plain HTTP:

curl -X POST https://idproval.com/api/v1/verifications \ -H "Authorization: Bearer $IDPROVAL_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "external_id": "order_abc123" }'

The response contains the hosted flow URL and the session identifiers:

{ "verification_id": "vrfy_01jt…", "url": "https://idproval.com/session/verification/…", "secret": "…", "created_at": "2026-05-06T14:22:01Z", "expires_at": "2026-05-07T14:22:01Z", "verification_options": { "language": { "auto_detect": true, "locale": null } } }

Store verification_id against your user record now. It is the key you will match on when the webhook arrives.

4. Send the user through the flow

Redirect the user to session.url, or open it in the hosted modal so they never leave your page. The flow handles capture, liveness, document scanning, language, and retries for you.

That URL carries the session secret in its query string, so it is a bearer credential: whoever holds it can open the session, see the submitted document data and complete the flow. Send it to the one user it was created for, and keep it out of your logs, your analytics, your error reports and your support inbox.

The modal approach is walked through step by step in the age verification modal guide.

Sessions expire. expires_at in the create response tells you when. Create a fresh session rather than reusing an expired URL.

5. Receive the verdict

When the user finishes, IDProval sends a signed verification:completed webhook to the endpoint configured for your organization. The webhook is the source of truth, so don't rely on the browser redirect, which the user can close or interrupt.

{ "event": "verification:completed", "occurred_at": "2026-05-06T14:24:55Z", "data": { "verification": { "id": "vrfy_01jt…", "external_id": "order_abc123", "status": "completed", "result": { "verdict": "auto_approved" }, "created_at": "2026-05-06T14:22:01Z", "completed_at": "2026-05-06T14:24:55Z" } } }

Verify the signature before you trust the body. See Webhooks. You can also poll GET /verifications/{'{'}verification_id{'}'} if you need the current state on demand.

Reading the verdict

A completed verification carries one of four verdicts:

• auto_approved passed every configured check. Let the user through.
• auto_rejected failed a check outright.
• manual_approved means a reviewer approved it after it was escalated.
• manual_rejected means a reviewer rejected it after it was escalated.

A session can also land on pending_manual, which arrives as a separate verification:manual_required event. That is not a final answer: a verification:completed event follows once a reviewer decides. Treat anything other than the four verdicts above as "not decided yet".

Next

• Authentication covers scopes, rotation and IP allowlists.
• Webhooks covers signature verification and the retry schedule.
• Errors covers what to do when a call fails.
• Production is the checklist to work through before you put real users through.