Verification requests

Create a verification

POST /api/v1/verifications
Authorization: Bearer sv_live_REDACTED
Idempotency-Key: case-8421-said-v1

{
  "service_code": "said_verification",
  "subject": "8001015009087",
  "purpose": "Employee onboarding for Example Ltd, case 8421",
  "authority_confirmed": true,
  "charge_approved": true
}

JSON response: completed

A successful new request returns 201. Values below are illustrative and contain no real personal data.

{
  "request_id": "svr_01J9EXAMPLE8421",
  "status": "completed",
  "service_code": "said_verification",
  "subject": "********9087",
  "credits_reserved": 1,
  "credits_charged": 1,
  "result": {
    "label": "Identity details matched",
    "outcome": "positive",
    "provider_reference": "[REDACTED]"
  },
  "created_at": "2026-09-09T12:30:00Z"
}

JSON response: manual review

An uncertain provider outcome returns 202. Keep the same idempotency key and wait for review; do not submit a second paid request.

{
  "request_id": "svr_01J9EXAMPLE8421",
  "status": "manual_review",
  "service_code": "said_verification",
  "credits_reserved": 1,
  "credits_charged": 0,
  "message": "The provider outcome requires human review.",
  "next_action": "Do not retry; contact authorised support."
}

JSON response: idempotent replay

Reusing the same Idempotency-Key returns the existing request rather than creating a duplicate charge.

{
  "request_id": "svr_01J9EXAMPLE8421",
  "status": "completed",
  "idempotent_replay": true,
  "credits_charged": 1
}

Response semantics