POST/v1/verify

Create a verification session

Starts a verification session for the guided live-camera flow. This endpoint no longer accepts an image and no longer performs an immediate match. It always returns a hosted verify_url.

Authentication

API key, as a bearer token. See Authentication.

Request body

Field	Type	Required	Description
external_user_id	string	required	Your own reference for this person.
full_name	string	optional	Optional display name stored on the session metadata.
redirect_url	string	optional	Where to send the browser after completion. Must be https:// and on your allowed redirect origins list.
metadata	object \| string (JSON)	optional	Arbitrary metadata attached to the verification session and echoed in the webhook.

POSThttps://api-faceverify.bluufun.com/v1/verify

Headers

Authorization: Bearer sk_live_...
Content-Type: application/json

Body (raw, JSON)

{
  "external_user_id": "user-001",
  "full_name": "Jane Doe",
  "redirect_url": "https://yourapp.com/verify/callback",
  "metadata": {
    "plan": "pro"
  }
}

Response

200 OK

{
  "success": true,
  "status": "verification_required",
  "verify_url": "https://verify.yourdomain.com/s/7yV0N3z8_26yZpxtUKZRVRvy04KeHT5-",
  "expires_at": "2026-07-05T20:40:06.547Z"
}

Send the user to verify_url to start the browser flow.

Error responses

Field	Type	Required	Description
400	—	optional	Missing external_user_id; invalid redirect_url; or a request still sending image data.
401	—	optional	Missing, malformed, or invalid API key.
403	—	optional	Your account is suspended.
429	—	optional	Rate limit exceeded.
500	—	optional	Session creation failed on the server.

The old immediate-match path is gone. Every verification now starts with a live browser session, even for users who already exist in your system.