# Verifai API

> B2B facial recognition REST API. Developers integrate via API keys; end users never touch Verifai directly.

## Documentation

- Quickstart: https://verifai.iqtbots.ai/docs/
- API reference (Swagger UI): https://verifai.iqtbots.ai/docs/api/
- OpenAPI JSON schema: https://verifai.iqtbots.ai/api/schema/
- Framework guides: https://verifai.iqtbots.ai/docs/integrations/
- AI-assisted integration: https://verifai.iqtbots.ai/docs/ai/

## Authentication

All recognition endpoints require:

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

API keys are created in the Verifai dashboard. The plain secret is shown once at creation.

## Base path

All recognition endpoints: `{base_url}/api/v1/`

## Core flows

1. Create collection — `POST /api/v1/collections/`
2. Enroll person — `POST /api/v1/collections/{collection_id}/persons/` (multipart: `external_id`, `image`, optional `display_name`, `metadata`)
3. Verify 1:1 — `POST /api/v1/verify/` (multipart: `collection_id`, `external_id` or `person_id`, `image`, optional `threshold`) — **preferred for login/check-in**
4. Identify 1:N — `POST /api/v1/identify/` (multipart: `collection_id`, `image`, optional `threshold`, `max_results`) — **linear O(n) scan; default max gallery 500**; use verify when user ID is known
5. Detect faces — `POST /api/v1/detect/` (multipart: `image`)

Map your application's user ID to Verifai `external_id` on enroll.

## Request format

- Image uploads: `multipart/form-data` with field name `image` (JPEG or PNG)
- JSON bodies: `Content-Type: application/json` for collection create/list

## Response envelope

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

Default match threshold: 0.4 cosine similarity (tunable per verify/identify request).

## Integration rules (important)

- Call Verifai from your **backend only**. Never embed API keys in frontend JavaScript or mobile apps. CORS is not enabled on the API.
- API versioning and breaking-change policy: see `docs/API_VERSIONING.md` in the repository.
- Store `VERIFAI_API_KEY` and `VERIFAI_BASE_URL` in environment variables.
- Handle `error.code` values: `no_face_detected`, `person_not_found`, `not_enrolled`, `gallery_too_large`, `rate_limit_exceeded`, `daily_quota_exceeded`, `image_quality_failed`.
- Identify is O(n) over the collection; do not use it for large galleries or when `external_id` is known — use verify instead.
- On HTTP 429, respect the `Retry-After` header.
- Tenant isolation: each API key is scoped to one organization; collections belong to that org.

## Webhooks (optional)

Configure webhook endpoints in the dashboard. Events include enroll, verify, identify. Verify `Verifai-Signature` HMAC on incoming payloads.

## Account setup

Developers register at https://verifai.iqtbots.ai/docs/ (dashboard or session API). Recognition calls use API keys only — not dashboard session cookies.