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

Check signatory

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

Check the signing Owner's PAN against the confirmed company's directors

The Owner enters their own PAN and the name on it; the register provider checks it against the directors and signatories of the registration confirmed by POST…Show moreThe Owner enters their own PAN and the name on it; the register provider checks it against the directors and signatories of the registration confirmed by POST /v1/activation/business-registration:confirm. DIRECTOR_MATCH completes rail step business_verification (no hosted KYB session needed); NOT_A_DIRECTOR is a 200 result, not an error: the step reads needs_you (needs[] signatory.pan) and the hosted KYB session (POST /v1/activation/verification-sessions) stays the fallback. result is x-extensible-enum. Before a registration is confirmed the check is 409 CONFLICT details.reason REGISTRATION_NOT_CONFIRMED. The PAN is sent to the provider and never stored or echoed: the answer carries panLast4 only. A PAN that does not match the pattern is 400 VALIDATION details.field pan. The check is for the signed-in Owner only: when the Owner's name is known (AccessContext.givenName and familyName), nameOnPan must equal givenName + " " + familyName compared without regard to case or whitespace, else 400 VALIDATION details.reason SIGNATORY_NOT_SIGNED_IN_USER and nothing is sent to the provider. At most 5 checks per tenant per UTC day (replays of an Idempotency-Key do not count): the sixth is 429 RATE_LIMITED details.reason SIGNATORY_ATTEMPTS_EXCEEDED with Retry-After (seconds to the next 00:00 UTC) and details.retryAfterMs; step business_verification then reads needs_you (needs[] kyb.hosted) and the hosted KYB session is the path. Human session only; Owner only. Idempotency-Key required. Audited (activation.signatory_checked, with the result and panLast4). method picks the check. PAN (the default when method is absent) is the check above and needs pan and nameOnPan (India). NAME_DOB needs dateOfBirth only: the signed-in Owner's name (AccessContext.givenName and familyName) and date of birth are checked against the directors, officers, members or managers the register names for the registration confirmed by scheme and number (GB, AE, US, CA). DIRECTOR_MATCH (GB, AE, CA) or OFFICER_MATCH (US, an officer or member named on the register) completes the signatory part of business_verification; NOT_A_DIRECTOR leaves it needs_you with hosted KYB the fallback. Exactly one method's fields: pan or nameOnPan with NAME_DOB, or dateOfBirth with PAN, is 400 VALIDATION details.field naming it, and a missing field of the method is 400 VALIDATION details.field naming it; NAME_DOB on an India registration is 400 VALIDATION details.field method (India checks by PAN). Either method needs a confirmed registration first (409 REGISTRATION_NOT_CONFIRMED, above). The date of birth is sent to the provider and not kept by this route (the business-people record holds the representative's). result also takes OFFICER_MATCH (x-extensible-enum); panLast4 is absent on NAME_DOB and method echoes the check made. The attempt limit above counts both methods.

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 bodySignatoryCheckRequest

  • panstringOptional
  • nameOnPanstringOptional
  • methodstringOptional
    PAN (absent means PAN; India) or NAME_DOB (the Owner's name and date of birth against the register's directors, officers or managers; GB, AE, US, CA)
  • dateOfBirthstring · dateOptional
    the signed-in Owner's date of birth, with NAME_DOB; not kept by the check

Responses

  • 200The check's result (a mismatch is a result, not an error)SignatoryCheck
  • 400ApiErrorResponse
  • 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 REGISTRATION_NOT_CONFIRMED — confirm a GST registration first; or IDEMPOTENCY_CONFLICTApiErrorResponse
  • 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
  • 429RATE_LIMITED SIGNATORY_ATTEMPTS_EXCEEDED — 5 signatory checks today; use hosted KYB or retry after 00:00 UTCApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501
    NOT_IMPLEMENTED — the business registration routes are not served here: details.reason CAPPED_FLOW_UNAVAILABLE when the capped flow is off, GST_REGISTER_UNAVAILABLE when no GST register provider is…Show moreNOT_IMPLEMENTED — the business registration routes are not served here: details.reason CAPPED_FLOW_UNAVAILABLE when the capped flow is off, GST_REGISTER_UNAVAILABLE when no GST register provider is configured (India), or REGISTER_UNAVAILABLE when no register provider is configured for the country. Not retryable.
    ApiErrorResponse
  • 502
    UPSTREAM_UNAVAILABLE — the register provider could not be reached, as GstRegisterUnreachable for every country.Show moreUPSTREAM_UNAVAILABLE — the register provider could not be reached, as GstRegisterUnreachable for every country. Nothing was stored.
    ApiErrorResponse

Errors you should handle

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

400VALIDATION
pan must be 10 characters, five letters, four digits and a letter.
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
Confirm the business's GST registration before checking a signatory.
not retryable
409IDEMPOTENCY_CONFLICT
Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed
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
429RATE_LIMITED
Too many signatory checks today. Verify the business through the hosted check, or try again tomorrow.
retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
The capped activation flow is not available on this deployment.
not retryable
502UPSTREAM_UNAVAILABLE
The GST register is not answering right now. Try again in a minute.
retryable