---
description: Integrate Verifai facial recognition API into this application
alwaysApply: false
---

# Verifai API integration

Use when adding face enrollment, verification (1:1), or identification (1:N) to this project.

## Docs (read before implementing)

- Quickstart: /docs/
- OpenAPI schema: /api/schema/
- Framework guides: /docs/integrations/
- Machine-readable summary: /llms.txt

Replace host with your Verifai deployment URL (e.g. `https://api.verifai.com`).

## Authentication

    Authorization: Bearer vf_test_<secret>   # sandbox
    Authorization: Bearer vf_live_<secret>   # production

Store the API key in environment variables (`VERIFAI_API_KEY`, `VERIFAI_BASE_URL`). **Never** expose the key in client-side code.

## Standard integration pattern

1. On user registration or profile setup: enroll their reference photo
   - `POST /api/v1/collections/{collection_id}/persons/`
   - multipart: `external_id` = this app's user ID, `image` = JPEG/PNG
2. On login or check-in: verify the live photo (**1:1 verify** — do not use identify when user ID is known)
   - `POST /api/v1/verify/`
   - multipart: `collection_id`, `external_id`, `image`, optional `threshold` (default 0.4)
3. Check `data.matched` and `data.similarity` in the JSON response

Optional: `POST /api/v1/identify/` for small unknown-probe watchlists only (linear O(n); default max ~500 faces). Returns `gallery_too_large` above the cap.

## Response handling

Success: `{"success": true, "data": {...}}`
Error: `{"success": false, "error": {"code": "...", "message": "..."}}`

Handle at minimum: `no_face_detected`, `person_not_found`, `not_enrolled`, `gallery_too_large`, `invalid_image`, `rate_limit_exceeded`, `daily_quota_exceeded`.

## Architecture

- All Verifai HTTP calls must run **server-side** (backend API route, job queue, etc.)
- The browser/mobile app uploads photos to **your** server; your server forwards to Verifai
- Map your user model primary key or stable ID to Verifai `external_id`

## Image requirements

- JPEG or PNG, field name `image`, multipart/form-data
- Clear front-facing photo; enroll and verify images should show one face