API referenceidentity
Get activation
GET
/v1/activationAccepts X-Api-Key · oauthClientCredentials · bearer
The activation rail — every step with its state and what is still needed
One rail per tenant, the same answer from any device.Show more
One rail per tenant, the same answer from any device. Steps carry state todo | in_progress | needs_you | in_review | done | blocked; every needs_you step names in needs[] the exact field or document still missing. States are derived from facts (for example sandbox_booking from firstSandboxOrderAt), never set by hand. Needs tenant:read, which the Owner and Admin role bundles carry; the users:manage fallback is retired; a human session or an API key (a sandbox key reads the rail of the tenant it belongs to). Step keys, states, tier and buildingIntent are x-extensible-enum: a client renders the values it knows and tolerates the rest. additive: the rail is derived per account type (accountType). A BUSINESS tenant keeps the nine steps above, unchanged. An INDIVIDUAL tenant has five: verify_email, sandbox_booking, identity_verification, terms, go_live — no business profile, no business verification, no money model, no wallet (an individual pays each booking by card through the payment provider's hosted checkout) and no API certification. identity_verification is done when an identity check (POST /v1/activation/identity-checks) is VERIFIED; its needs[] names what is missing (taxId). go_live is blocked until identity_verification and terms are done, and one Owner's sign-off is enough (GET /admin/v1/go-live requiredSignoffs 1). identityCheck carries the latest check, null until one ran; the full identity number is never returned. flow says which rail the tenant is on (NINE_STEP, as above, or CAPPED) and every step carries required. On CAPPED the required steps are business_verification (GST register look-up, confirm, signatory check; hosted KYB the fallback), money_model (WALLET, CARD with a saved method, or the ops-routed models) and terms, plus fund_wallet only when the model is WALLET (verify_email is required too, always done at sign-up); every other step is required false: sandbox_booking and certification (recommended), business_profile (completed by the registration confirm on the India path; elsewhere the hosted KYB collects the company details) and go_live (done when the tenant turns live). The transition that completes the last required step activates the tenant itself (TRIAL to LIVE, actor system:capped-auto-live) with tier LIVE_CAPPED and a daily cap (limits; GET /v1/activation/limits), with no go-live signoff and no ops approval; go_live then reads done. A step in_review (a KYB case the provider reviews) never completes it. Every listed step but sandbox_booking is required. business_profile is done when country, businessStructure, industry, website (or noWebsite with productDescription), phone and monthlyVolume are set (PATCH /v1/activation/profile). business_verification is done only when the registration is confirmed (by GSTIN, or by scheme and number) or the hosted KYB documents are approved, the signatory matched (POST /v1/activation/signatory-checks) and the business people are submitted (PUT /v1/activation/business-people with owners, or noOwnerAt25Percent true). The CAPPED flow is for BUSINESS tenants only; a person selling in their own name signs up as an INDIVIDUAL account and is never on this rail. money_model is done for CARD with a saved method, for WALLET with an elected currency and a wallet balance above zero, and for OWN_ACCREDITATION or BYOC when the operator review (OpsApproval kind MONEY_MODEL_REVIEW) is approved; it reads in_review meanwhile. go_live is required and reads done when the tenant is LIVE: on CAPPED going live is now the Owner's explicit POST /v1/activation:go-live, which replaces the automatic promotion of 1.51.0 (no step transition activates the tenant by itself any more). workEmail says whether a work e-mail must be proved first (POST /v1/activation/work-email:send-code, then:confirm); go-live is refused while workEmail.required is true and workEmail.verifiedAt is null. Test mode (the sandbox twin and sandbox keys) is unaffected. on CAPPED, business_verification is the verification provider's verdict. It is done only when the provider's case is verified (with the registration confirmed where the country has a register, the signatory matched and the business people submitted); submitting the forms is not enough. businessVerification carries the case: status not_submitted leaves the step as round 2 reads it (what is still to fill), in_progress (submitted, the provider has not answered) reads in_progress, in_review reads in_review, needs_more reads needs_you with needs[] the outstanding requirement codes (businessVerification.outstanding), rejected reads blocked, verified reads done. A client re-reads this rail while businessVerification.status is in_progress or in_review. going live on CAPPED is an operator review. POST /v1/activation:go-live opens it and goLiveReview carries it (GoLiveReview: status, submittedAt, decidedAt, expectedBy, note, and per product its status and checks business_details and test_calls); the tenant stays TRIAL until an operator approves. go_live reads in_review while the review is in_review, needs_you (needs[] go_live.changes_requested) on changes_requested, blocked (needs[] go_live.rejected) on rejected and done once approved (tier LIVE_CAPPED). It replaces "once verified, going live is immediate" above. A client re-reads this rail while goLiveReview.status is in_review. sandbox_booking is required on CAPPED (owner direction 2026-10-29): the test calls (search, reprice, orders, cancel in the sandbox) for every requested product must be seen before an operator can approve; the request itself may come first, and sandbox_booking's needs[] names what is missing (<product>.<verb>).Request body
This operation takes no request body.
Responses
- 200The railActivationState
- 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. - 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. - 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
Errors you should handle
Branch on code and honour retryable — never on the HTTP status alone.
| 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 |
| 414 | VALIDATION The request URI is longer than 8 KiB. | not retryable |
| 500 | INTERNAL An unexpected error occurred. Quote the traceId to support. | retryable |