KYC API for identity verification

An ID verification API for marketplaces, gig and rental platforms, online education and gaming. Create a verification with one API call, send the person to the link, and receive a signed webhook with the decision. Then read back the data from their ID. ProofAge reads ID documents from 190+ countries.

$0.30 per verification, everything included.

No card and no time limit. Test mode is free.

How the KYC verification API works

  1. 1. Create a verification

    Send POST /verifications and get back a url for the person to open. Pass external_id for your user, callback_url for where the browser returns, and external_metadata to get back in the API and webhooks.

  2. 2. The person verifies

    They photograph their ID and take a live selfie, on a hosted page, on your own domain, or embedded in your site with the Browser SDK.

  3. 3. Get the result

    A signed webhook arrives each time the verification's status changes. Read the details while the data is kept with GET /verifications/{id} and GET /verifications/{id}/document.

Create a verification with the Node.js SDK

// npm install @proofage/node; reads PROOFAGE_API_KEY and PROOFAGE_SECRET_KEY
import { ProofAgeClient } from '@proofage/node';

const client = new ProofAgeClient();
const verification = await client.verifications().create({
  external_id: 'user_12345',
  callback_url: 'https://yourapp.example/verified',
});
// send the person to verification.url

Receive the result in a route handler

import { webhookHandler } from '@proofage/node';

export const POST = webhookHandler(async (payload) => {
  // payload.verification_id, payload.status, payload.reason
});

The handler checks the webhook signature for you.

Read the document data: GET /verifications/{id}/document

{
  "document": {
    "type": "passport",
    "issuing_country": "FRA",
    "issuing_subdivision": null,
    "fields": {
      "first_name": "Marie",
      "last_name": "Martin",
      "date_of_birth": "1990-04-12",
      "nationality": "FRA",
      "document_number": "18AB12345",
      "issue_date": "2018-05-03",
      "expiry_date": "2028-05-02"
    }
  }
}

Illustrative values, shortened; the exact formats are in the API reference. Fields the document doesn't show are null, and the response also lists links to the captured images.

The base URL is https://api.proofage.net/v1; the paths on this page are relative to it. Every request carries your workspace API key (the public key) in X-API-Key and an HMAC-SHA256 signature made with your secret key in X-HMAC-Signature. The SDKs sign requests and check webhook signatures for you.

What the identity verification API returns

The webhook tells you the decision. The API gives you the rest: the status and reason, the data read from the document, and links to the captured images.

Decision

status (approved, declined, resubmission_requested, abandoned or expired) and a reason when declined, with your external_id and external_metadata.

Document data

Document type, issuing country and subdivision. First, middle and last name, date of birth, gender, nationality, place of birth and address when the document shows them. Document number, issue date and expiry date.

Duplicates

duplicate_check shows whether the same person has already verified with you, so a second account is flagged even with a new email. Face and device blocklists are included.

Speed

95% of verifications return a decision in under 2 seconds after submission, and 99% in under 3 seconds.

What the person sees

A short flow under your brand

Consent, then a photo of the front of the ID and the back unless it is a passport, each checked on the spot with a retake if it can't be read. Then a live selfie with head-turn prompts. An uploaded photo is not accepted in place of the selfie. White-label is included: your logo, your colors, your own domain, or embedded in your page with the Browser SDK.

From computer to phone

On a computer, the person scans a QR code and continues on their phone. The computer screen updates when they finish, and the browser returns to your callback_url.

In the person's language

English, Spanish, French, German, Japanese, Chinese and more, set by a lang parameter in the link, the Browser SDK language option, or the browser's language.

In a mobile app

The web flow works in a WebView or as a link opened from your app. There is no native iOS or Android SDK today; if you need one, we will build it with you.

Integrate in a day, or in a couple of hours with an AI agent

With the SDKs, a typical integration is built and tested within a day. With an AI coding agent using the MCP server, it takes a couple of hours.

We help you integrate: ready SDKs, an MCP server and an integration prompt for AI coding agents, and direct help from the developers who built it. More for developers

Free KYC API test mode

Test mode uses its own keys and is always free. Create a verification, set its outcome with POST /verifications/{id}/test-outcome and watch the webhook arrive, so you test approved and declined results end to end without spending live verifications.

What the ID verification API checks

Identity verification (KYC) for your team

The document

The machine-readable data, including the MRZ and the PDF417 barcode on US and Canadian licenses, is read and cross-checked with the front. The layout is checked against the document's template, and the dates against each other: expiry, and issue date against date of birth.

The face

The photo on the ID is matched to the selfie, and the selfie is taken live with a liveness check.

The same person, later

Create a selfie-only session with reference_verification_id to confirm that the person behind an approved verification is back. Face re-verifications are not billed.

KYC API pricing

Full pricing

$0.30 per verification, everything included.

  • The first 500 verifications are free, with no card and no time limit.
  • After that, a $30 monthly minimum that your usage counts toward. It covers 100 KYC verifications.
  • Billed once, when a verification reaches a decision. Abandoned and expired verifications are free, and resubmissions we request are not billed again. Test mode is free.

Higher volume or a competing quote? Talk to us.

Where the data is stored

Security and data handling

In the EU on Google Cloud by default, or in the US on request, encrypted in transit and at rest. Photos and verification data are kept for 30 days by default, and you can change that period. Read the data processing agreement.

Questions about the KYC API

What is a KYC API?

A KYC API lets your product verify a person's identity from code. You create a verification, the person photographs their ID and takes a live selfie, and the API returns a decision and the data read from the document.

Is a KYC API the same as an ID verification API or an identity verification API?

In practice, yes. All three names describe an API that checks a person's ID document and matches it to a live selfie. Strictly, KYC can also include sanctions and PEP screening, which ProofAge does not offer today. Whichever name you search for, an API for KYC verification does the same job: it takes an ID document and a selfie and returns a decision with the document data.

How long does integration take?

With the SDKs, a typical integration is built and tested within a day. With an AI coding agent using the MCP server and the integration prompt, it takes a couple of hours.

Can users stay on our site and see our brand?

Yes. Embed the flow in your page with the Browser SDK or run it on your own domain, with your logo and colors. White-label is included in every account.

Does it work in a mobile app?

Yes, through the web flow: open the link or load it in a WebView. There is no native iOS or Android SDK today. If you need one, contact us and we will build it with you.

Which languages does the flow support?

English, Spanish, French, German, Japanese, Chinese and more. The language comes from a lang parameter in the link, the Browser SDK language option, or the person's browser language.

Do you offer AML, sanctions or PEP screening?

Not today. ProofAge verifies identity and age: ID scan, face match, liveness and fraud checks. If you need screening alongside that, get in touch: we have ideas for how to add it and are ready to work on it with you.

What happens if a photo is poor or a verification is declined?

Each photo is quality-checked while the person is still in the flow, and they retake it if it can't be read. If we ask the person to try again because of glare or blur, the new attempt is not billed again. A declined verification comes with a reason in the webhook and the API.

Is there a sandbox?

Yes. Test mode has its own keys and is always free. Set a verification's outcome with POST /verifications/{id}/test-outcome to test approved and declined results end to end.

Is there a free KYC API?

Partly. Test mode is free forever: you can build and test the whole integration without paying. In live mode the first 500 verifications are free, with no card required. After that you pay $0.30 per verification. There is no unlimited free live tier, because every live verification has a real processing cost.

How is it billed?

$0.30 per verification, billed once when the verification reaches a decision. Abandoned and expired verifications, resubmissions we request, face re-verifications and test mode are free.

A direct line to the developers who built it

Write to us on LinkedIn, by email or in the dashboard chat. The developers who built ProofAge answer themselves, weekends included.

Get your API keys

Run the full flow in test mode, then go live with 500 free verifications.