API referenceidentity
Start verification session
POST
/v1/activation/verification-sessionsIdempotency-Key requiredAccepts bearer
Start or resume the business verification (KYB) session — rail step 4
Opens the provider's hosted session, or resumes the open one (same providerRef), and answers where to send the user: hostedUrl (a redirect) or embedToken (the provider's embedded component), with the…Show more
Opens the provider's hosted session, or resumes the open one (same providerRef), and answers where to send the user: hostedUrl (a redirect) or embedToken (the provider's embedded component), with the status and the provider's outstanding list. Apiq prefills what it knows (legal name guess, domain, country) and stores only the provider reference, outcome, risk tier and timestamps, never a document. A tenant already verified is 409 CONFLICT details.reason ALREADY_VERIFIED. When the provider cannot be reached the answer is 502 UPSTREAM_UNAVAILABLE (retryable) and the rail shows step business_verification blocked; a deployment with no provider configured is 501 NOT_IMPLEMENTED details.reason KYB_UNAVAILABLE. Human session only; the caller must be an Owner, otherwise 403 PERMISSION_DENIED details.reason OWNER_ONLY. Idempotency-Key required. Audited.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 more
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 is 409 IDEMPOTENCY_IN_PROGRESS.
Request body
- returnUrlstring · uriOptionalWhere the provider's hosted flow sends the user back (a console URL)
Responses
- 200The session to send the user to (opened or resumed)VerificationSession
- 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
- 401ApiErrorResponse
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — 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. - 403ApiErrorResponse
- 405ApiErrorResponse
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 more
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). Not retryable as sent. - 409CONFLICT ALREADY_VERIFIED — the business is verified; nothing to resumeApiErrorResponse
- 413ApiErrorResponse
VALIDATION — the request body is larger than the surface's limit.Show more
VALIDATION — 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. - 414ApiErrorResponse
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 more
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). Not retryable as sent: send long input in the body of a POST. - 415ApiErrorResponse
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more
VALIDATION — 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. - 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
- 501NOT_IMPLEMENTED KYB_UNAVAILABLE — no verification 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.
| 400 | VALIDATION message.intent.checkOut must be after message.intent.checkIn | not retryable |
| 400 | UNKNOWN_DOMAIN Unknown domain 'HOTELS'. Did you mean HTL? | not retryable |
| 401 | UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry. | not retryable |
| 403 | PERMISSION_DENIED Reading wallets needs the finance:read permission. | not retryable |
| 405 | VALIDATION This method is not served. | not retryable |
| 409 | CONFLICT The business is already verified. | not retryable |
| 413 | VALIDATION The request body is larger than this API accepts (262144 bytes). | not retryable |
| 414 | VALIDATION The request URI is longer than 8 KiB. | not retryable |
| 415 | VALIDATION Send application/json. | not retryable |
| 500 | INTERNAL An unexpected error occurred. Quote the traceId to support. | retryable |
| 501 | NOT_IMPLEMENTED Business verification is not available on this deployment. | not retryable |
| 502 | UPSTREAM_UNAVAILABLE Every supplier for HTL is circuit-open; no fan-out was attempted | retryable |