KYC: identity verification

KYC at Bouncer is verification with an identity document. The person scans their face and then a physical identity document, on a page hosted by Bouncer. Bouncer checks that the document photo matches their face and that the document shows they meet your age target, and tells your server whether they passed.

It is the Age Verification API with one difference: the document is mandatory. You ask for it by sending force_kyc: true together with force_verification: true when you create the session, or by turning on Force KYC Verification on a device. Integrating KYC explains why you need both fields.

KYC or age verification alone

With age verification alone, a face scan approves the person when their age estimate clears your target, and a document is asked for only when it does not. With KYC, every approval rests on a document check. The face scan alone never approves.

Use KYC when:

• the rules that apply to you, or your own policy, require each approval to be backed by an identity document rather than an age estimate;
• you want a document check every time, even for a person who passed a Bouncer check recently in the same browser.

Age verification alone is enough when an age estimate is acceptable for your case. It is also shorter for the person whenever the estimate clears the target, because they do not need a document at hand.

KYC does not tell you who the person is. If you need their name, date of birth or document details, Bouncer does not provide them (see What you do not get back).

What is checked

A KYC session is approved only when all of these hold:

1. A live person. The face scan confirms that a real person is in front of the camera. Without that, the document step does not start and there is no result.
2. A physical document. The document is recognized as a physical identity document.
3. The face matches the document. The photo on the document matches the face scanned in the same session.
4. The age. The age on the document, in whole years from the date of birth printed on it, is at least your age_target. When the date of birth cannot be read, the age is not taken from it: Document check explains how such a document is handled.

The face scan also produces an age estimate, but in a KYC session that estimate cannot approve. If the document fails any condition, the session ends with success: false, and the person can try again with the document while the session is open. No documented field says which condition failed.

age_target takes the same values as in age verification: 8, 13, 16, 18, 21, 25 or 30.

The same API as Age Verification

Everything except the two fields above is shared, and documented once in the Age Verification section:

• the base URL https://app.bouncer.digital, API tokens and the API Secret;
• the endpoints POST /api/v2/session, GET /api/v2/session/{id} and POST /api/v2/device/{deviceCode}/session-url;
• session statuses, expiry, webhooks and their signature, the redirect with its signed jwt, and devices.

This section covers only what is specific to KYC.

How it works

1. Your server creates a session with POST /api/v2/session, including force_kyc: true and force_verification: true. The response has the session id and a verify_url.
2. You send the person to verify_url: a redirect, a new tab, or a QR code they scan.
3. The person scans their face. The scan confirms that a live person is present.
4. The person scans their identity document, right after, in the same flow. The page tells them that a document is needed and guides them through photographing it.
5. Bouncer decides and records the verdict (status: completed, success: true or false) and sends validation.completed to your webhook_url.
6. On success, the person's browser returns to your redirect_url with a signed jwt query parameter. On failure there is no redirect: the person stays on the Bouncer page, which offers to try again with the document while the session is open.
7. Your server confirms with GET /api/v2/session/{id} before it unlocks anything.

What you get back

• success is the verdict: true when the document passed, false when a document did not pass, null while there is no verdict.
• metadata is what you sent when you created the session. Once a result is recorded, it also holds a facetec block. That block is reserved: its content is not part of the API contract and may change, so do not build logic on it, and do not send a facetec key yourself.

What you do not get back

The result says whether the person passed. It does not identify them. No API response, webhook or token contains:

• the person's name, date of birth, nationality or address;
• the document number, type, issuing country or expiry date;
• an image of the face or of the document.

No documented field gives the reason for a failure. The result does not repeat the age target or the options you sent either: if you need them later, keep them on your side or put them in your metadata.

Next steps