API reference

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

{
  "api_key": "lv_9f2c4e8a…",
  "test_api_key": "lv_test_7b1d3f0c…",
  "client_id": "a1b2c3d4e5f6a7b8",
  "credits": 1000,
  "message": "Save both keys — each is shown only once."
}

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

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

$ 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"
  }
}

# 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"

$ curl -X POST https://liveliness.neetix.in/v1/document/id \
    -H "Authorization: Bearer $LIVELINESS_API_KEY" \
    -F "back=@license-back.jpg" \
    -F "front=@license-front.jpg"

{
  "status": "success",
  "aamva": {
    "version": 8, "issuer_id": "636014", "doc_type": "DL",
    "first_name": "JANE", "middle_name": "MARIE", "last_name": "SAMPLE",
    "dob": "1986-06-06", "expiry": "2031-06-06", "issue_date": "2015-08-24",
    "license_number": "D12345678",
    "address": { "street": "1234 MAIN STREET", "city": "SACRAMENTO",
                 "state": "CA", "postal": "958180000" },
    "sex": "female", "height": 173, "eye_color": "GRN",
    "country": "USA", "real_id_compliant": null
  },
  "face_found": true,
  "forensics": { "screen_replay_score": 8.5, "synthetic_score": 0.0,
                 "high_freq_ratio": 0.31, "spectral_peak": 12.4 },
  "checks": { "barcode_decoded": true, "aamva_parsed": true,
              "expired": false, "underage_18": false, "underage_21": false,
              "dates_valid": true },
  "warnings": []
}

$ 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": 1000, "balance_after": 1000, "reason": "signup_bonus",
      "ref_id": null, "created_at": "2026-08-09T18:30:11Z" }
  ]
}

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

# 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)>