API reference

POST /v1/signup issues a DB-backed API key. The key is shown once — store it immediately. Every request to a /v1 endpoint must carry the bearer header; errors come back as JSON (see Errors).

$ curl -X POST https://liveliness.neetix.in/v1/signup \
    -H "Content-Type: application/json" \
    -d '{"email":"you@company.com"}'

{
  "api_key": "lv_live_9f2c4e8a…",
  "client_id": "a1b2c3d4e5f6a7b8",
  "credits": 500,
  "message": "Store this key now — it will not be shown again."
}

Every /v1 endpoint takes the same header — Authorization: Bearer <api_key>. Keys are issued at signup and shown once; balance, ledger and usage for a key live in the console.

A missing or invalid key returns 401 with message_code: "unauthorized". The cheapest way to verify a key is GET /v1/billing/balance — it reads your prepaid balance without consuming credits.

$ curl https://liveliness.neetix.in/v1/billing/balance \
    -H "Authorization: Bearer $LIVELINESS_API_KEY"

{ "status": "success", "client_id": "a1b2c3d4e5f6a7b8", "balance": 500, "metered": true }

Body is multipart/form-data. The response keeps a Digitap-compatible envelope (top level + result) and adds a lowercase aggregate verdict — approved | review | declined — plus a warnings[] array of { code, severity, description } risk signals such as LIVENESS_FACE_ATTACK, LOW_FACE_QUALITY and MULTIPLE_FACES_DETECTED.

$ curl -X POST https://liveliness.neetix.in/v1/face/face-match \
    -H "Authorization: Bearer $LIVELINESS_API_KEY" \
    -F "person=@selfie.jpg" \
    -F "card=@aadhaar.jpg" \
    -F "clientRefId=lead-8841"

{
  "status": "success",
  "statusCode": 200,
  "clientRefId": "lead-8841",
  "requestId": "018f6a2e-…-v7",
  "verdict": "approved",
  "warnings": [],
  "result": {
    "is_same_face": true,
    "same_face_confidence": 87.34,
    "cosine_similarity": 0.5123,
    "decision": "APPROVED",
    "match_threshold": 70.0,
    "liveness_score": 92.1,
    "liveness_status": "genuine",
    "spoof_detected": false,
    "liveness_threshold": 70.0,
    "person_quality": { "sharpness": 210.4, "brightness": 129.7, "score": 88.2, "blurry": false },
    "card_quality":   { "sharpness": 160.1, "brightness": 141.2, "score": 74.0, "blurry": false },
    "model_version": "neetix-face-v1"
  }
}

If no face is found in either image the call returns 422 with the Digitap-compatible fail envelope: { "status": "fail", "statusCode": 422, "error": "Face not found in one or both of the images." }.

# 1. start a session — returns a randomized challenge script
$ curl -X POST https://liveliness.neetix.in/v1/session/start \
    -H "Authorization: Bearer $LIVELINESS_API_KEY"

{ "session_id": "9f2c4e8a…", "challenges": ["center", "left", "right"] }

# 2. capture one frame per challenge, then verify
$ curl -X POST https://liveliness.neetix.in/v1/session/9f2c4e8a…/verify \
    -H "Authorization: Bearer $LIVELINESS_API_KEY" \
    -F "frame_0=@center.jpg" -F "frame_1=@left.jpg" -F "frame_2=@right.jpg"

The stream's temporal model scores every frame for sustained liveliness, real head motion and identity continuity — a mid-stream face-swap raises IDENTITY_SWITCH, a static photo raises NO_MOTION, and looped-video replays are rejected. A browser-hosted capture page is available at GET /capture if you don't want to ship an SDK.

The gallery is tenant-scoped by API key. Face-match automatically searches it to raise DUPLICATED_FACE and FACE_IN_BLOCKLIST on repeat or blocklisted faces.

$ curl https://liveliness.neetix.in/v1/billing/balance \
    -H "Authorization: Bearer $LIVELINESS_API_KEY"

{ "status": "success", "client_id": "a1b2c3d4e5f6a7b8", "balance": 431, "metered": true }

$ curl "https://liveliness.neetix.in/v1/billing/ledger?limit=100" \
    -H "Authorization: Bearer $LIVELINESS_API_KEY"

{
  "status": "success",
  "client_id": "a1b2c3d4e5f6a7b8",
  "balance": 431,
  "entries": [
    { "delta": -2,  "balance_after": 431, "reason": "charge:face_match",
      "ref_id": "018f6a2e-…-v7", "created_at": "2026-08-10T09:14:02Z" },
    { "delta": 500, "balance_after": 500, "reason": "signup_bonus",
      "ref_id": null, "created_at": "2026-08-09T18:30:11Z" }
  ]
}

Ledger reason values: signup_bonus, charge:<endpoint>, topup:dodo, refund:<endpoint>, refund:dodo. When the balance runs out, billable calls return 402 with message_code: "insufficient_credits" — handle it like a quota error.

Once enabled, POST /v1/billing/topup with { "pack": "starter", "email": "billing@co.com" } returns { checkout_url, session_id, credits, pack }. Open checkout_url — a Dodo Payments hosted checkout with UPI, cards and PayPal. Credits are granted when the payment settles (Indian UPI and cards can take up to ~48 h) — poll the balance or watch the ledger for a topup:dodo entry.

{
  "statusCode": 402,
  "message": "Insufficient credits. Top up to continue.",
  "message_code": "insufficient_credits"
}

Exception: the face-match no-face case also ships the Digitap-compatible fail envelope (status: "fail" + an error string) so existing Digitap integrations keep working unchanged.

When signing is enabled, every verification response carries an X-Neetix-Signature header — an Ed25519 signature over the exact response bytes. Fetch the public key from GET /v1/verification-key, pin it, and verify the signature before parsing the body.

Results can also be mirrored to your endpoint as signed webhooks: each result is POSTed with an X-Signature-V2: sha256=<hex> header — an HMAC-SHA256 of the raw body using your webhook secret. Recompute it and compare in constant time before trusting the payload.

# fetch the Ed25519 verification key once and pin it
$ curl https://liveliness.neetix.in/v1/verification-key

# then, on traffic from us:
X-Neetix-Signature: <base64 Ed25519 signature over the exact response bytes>
X-Signature-V2:     sha256=<hex HMAC-SHA256(webhook_secret, raw_body)>

Every SDK wraps the same HTTPS + JSON contract documented above, including the Digitap-compatible face-match envelope. Client SDKs are pre-release — interfaces may change before 1.0. If you don't want to ship one, the REST API and the hosted capture page at GET /capture cover the full flow.