Skip to content
ApiqDevelopers
API v1.64.0Open console
API referenceidentity

Start identity check

POST/v1/activation/identity-checks
Idempotency-Key requiredAccepts bearer

Check the person's identity (India PAN) — the individual rail's identity_verification step

Checks one identity number against the identity provider and answers the result at once (KYC-lite: no document, no image, no upload).Show moreChecks one identity number against the identity provider and answers the result at once (KYC-lite: no document, no image, no upload). The only scheme is IN_PAN: taxId.value must match ^[A-Z]{5}[0-9]{4}[A-Z]$ (400 VALIDATION details.reason TAX_ID_FORMAT otherwise; the server checks it, not a schema pattern, so other schemes can be added), and for an INDIVIDUAL account the fourth character must be P, a personal PAN (400 VALIDATION details.reason PERSONAL_PAN_REQUIRED). Another scheme is 400 VALIDATION details.reason UNSUPPORTED_SCHEME. fullName is the name exactly as on the PAN card; the provider compares it (nameMatched). A check the provider answers is a 200 whatever its outcome: VERIFIED ticks rail step identity_verification; FAILED (failureReason NAME_MISMATCH, NOT_FOUND or INACTIVE) leaves the step needs_you and the person may try again; PENDING means the provider answers later and GET /v1/activation shows the outcome. The latest check also reads back as ActivationState.identityCheck. The full number is never stored, logged or returned: the platform keeps the masked value (first five and last character), a keyed hash of the number (to recognise a repeat), the result, the name and the time — no document and no image. A tenant whose latest check is VERIFIED is 409 CONFLICT details.reason ALREADY_VERIFIED. When the provider cannot be reached the answer is 502 UPSTREAM_UNAVAILABLE (retryable). Human session only; the caller must be an Owner, otherwise 403 PERMISSION_DENIED details.reason OWNER_ONLY. Idempotency-Key required: a replay answers the first check, the number is not sent to the provider twice. Audited, with the masked value only.

Headers

  • Idempotency-KeystringRequired
    Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show moreMandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request bodyIdentityCheckRequest

  • taxIdTaxIdentifierRequired
    A tax identity number and its scheme. IN_PAN is India's Permanent Account Number: ten characters ^[A-Z]{5}[0-9]{4}[A-Z]$, checked by the server (400 VALIDATION details.reason TAX_ID_FORMAT) rather…Show moreA tax identity number and its scheme. IN_PAN is India's Permanent Account Number: ten characters ^[A-Z]{5}[0-9]{4}[A-Z]$, checked by the server (400 VALIDATION details.reason TAX_ID_FORMAT) rather than by a schema pattern, so other schemes can be added; for an INDIVIDUAL account the fourth character must be P, a personal PAN (400 VALIDATION details.reason PERSONAL_PAN_REQUIRED). A scheme the server does not take is 400 VALIDATION details.reason UNSUPPORTED_SCHEME. value is write-only: no response carries it.
    2 child attributes
    • schemestringRequired
    • valuestringRequired
      The identity number as issued, upper case, no spaces; never returned, logged or stored in full
  • fullNamestringRequired
    The person's name exactly as on the PAN card; the provider compares it with the holder's name

Responses

  • 200The check as the provider answered it (VERIFIED, FAILED or PENDING)IdentityCheck
  • 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
  • 401
    UNAUTHENTICATED — missing or expired token.Show moreUNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
    ApiErrorResponse
  • 403ApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 409CONFLICT ALREADY_VERIFIED — the person's identity is verified; nothing to checkApiErrorResponse
  • 413
    VALIDATION — the request body is larger than the surface's limit.Show moreVALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 415
    VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show moreVALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501NOT_IMPLEMENTED IDENTITY_CHECK_UNAVAILABLE — no identity provider is configured on this deploymentApiErrorResponse
  • 502Also the order read routes (getOrder, listOrderDocuments, listOrderEvents, searchOrders) when the order store times out: details.store names the store, retryable true.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400VALIDATION
message.intent.checkOut must be after message.intent.checkIn
not retryable
400UNKNOWN_DOMAIN
Unknown domain 'HOTELS'. Did you mean HTL?
not retryable
401UNAUTHENTICATED
The bearer token is expired. Re-authenticate and retry.
not retryable
403PERMISSION_DENIED
Reading wallets needs the finance:read permission.
not retryable
405VALIDATION
This method is not served.
not retryable
409CONFLICT
The identity is already verified.
not retryable
413VALIDATION
The request body is larger than this API accepts (262144 bytes).
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
415VALIDATION
Send application/json.
not retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
Identity checks are not available on this deployment.
not retryable
502UPSTREAM_UNAVAILABLE
Every supplier for HTL is circuit-open; no fan-out was attempted
retryable