API reference

Errors

Failures use one JSON shape. The code is stable. The message is for a person.

{
  "error": {
    "code": "invalid_request",
    "message": "sessionId: must be printable ASCII without spaces"
  }
}

Responses send Cache-Control: no-store. Do not retry a 4xx as if it might succeed unchanged. A 402 means the account needs a plan or has used its included checks. A 409 session_closed on create means that sessionId is finished: use a new one. Repeating an open sessionId returns 200, not an error.

HTTP	Code	When
400	`invalid_json`	The body is not JSON.
400	`invalid_request`	A field failed validation. `message` names the field.
400	`invalid_webhook_url`	The webhook URL is not public HTTPS on port 443, or it contains credentials.
400	`webhook_host_unresolved`	The webhook host did not resolve.
401	`unauthenticated`	The bearer token is missing, unknown, or revoked.
402	`trial_exhausted`	The free allowance is used up.
402	`allowance_exhausted`	This billing period’s included checks are used up.
404	`not_found`	No session exists for that `sessionId` on this account.
409	`session_closed`	Create was called with a `sessionId` that has already finished.
409	`not_open`	Cancel was called on a session that is already finished.
413	`too_large`	The JSON body is over 256 KB. Images and video are not sent to the API.
500	`internal_error`	Something failed on our side. Retry create with the same `sessionId`.

A 5xx or a network timeout on create is safe to retry with the same sessionId. If the first call succeeded, the retry returns the existing session.

What the guest can use

Passports and driving licences issued in the United Kingdom (GB), Ireland (IE), and the United States (US). A passport is the photo page only. A driving licence is the front and the back. The guest also holds that same document beside their face.