API-based ID verification

API-based ID verification lets your own software open a check and hear the result, without you building document capture. The guest still has to use a camera. The API is how that camera check joins the signup or the ticket sale, so the person is pre-vetted before they arrive.

Protect Events exposes this as a session. You choose the reference (sessionId), you choose the minimum age, and you receive a URL. The guest opens that URL on their phone. Webhooks tell you when the status moves, including when a case is waiting in the review pipeline you manage.

A checkout-shaped request

This is the shape of a ticket check. Keys stay on your server.

POST /api/v1/verification-sessions
Authorization: Bearer vm_live_...

{
  "sessionId": "order-1842",
  "minimumAge": 18,
  "metadata": { "event": "Saturday", "order": "1842" }
}

The response includes the same sessionId, a hosted url, the status (starts as created) and the minimumAge. Send the guest to that URL from the signup or the order email. You can also pass a webhook URL, and success or failure return URLs, when the check sits inside a longer purchase.

Metadata comes back untouched, which is how you keep your own order id attached without inventing a second database.

What you get back

When a decision exists, the payload carries the outcome: approved, declined or needs_review. A decline includes reasons, for example under age, an expired document, or a face that does not match. Review flags describe why the case is in your pipeline: layout, possible tampering, or a possible photo of a screen. The identity block includes the age derived from the date of birth when the document could be read.

You do not have to poll if you take webhooks. Useful moments include the guest starting, the document being captured, processing, needs review, approved, declined, a later change of decision, cancellation, and expiry. A session that nobody finishes expires after 24 hours.

Sign the webhook with the secret you were given, and reject anything that arrives without a valid signature. Treat the API key like a password. The platform page shows this split: phone for the guest, your pipeline for review, server for the key.

Why the phone step stays

An API cannot photograph a passport. The guest still completes a short face capture and a photo of them holding the document, on their own phone, before the event. The API’s job is to start that flow with the right age rule and to land the result where signup or ticketing can use it. Treat needs_review as waiting, not as approved, until your team has decided.

A clean integration, in order

1. Create a server-side key in the operator console. Do not ship it to a browser or an app binary.
2. Create one session per person you intend to check, at signup or checkout. Reuse the same sessionId only when you mean the same check.
3. Show the hosted URL as a link in the journey they are already in.
4. Verify webhook signatures, then store the outcome against your reference.
5. If your team changes a decision in the review pipeline, listen for the change so an earlier approval can be reversed in your system.

White-label wording on that hosted URL is covered in white-label ID verification. Pricing, including the trial, is on the pricing page.