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

Verify signup

POST/v1/signup/verify

Self-serve sandbox signup, step 2 — spend the code; get an evaluation tenant and a sandbox key

Provisions an EVALUATION tenant in TRIAL with the person as its admin under the password they chose (12 to 1024 characters), and mints a sandbox key returned here ONCE.Show moreProvisions an EVALUATION tenant in TRIAL with the person as its admin under the password they chose (12 to 1024 characters), and mints a sandbox key returned here ONCE. A wrong, expired, spent or exhausted code (6 digits, 15 minutes, at most 5 attempts) is one and the same 400. served since 1.18.1, additive: (1) password is optional — the password moves out of signup and the person sets a password later from the console; when sent it keeps the 12 to 1024 rule. An account created without one has no password until it is set, so POST /v1/auth/login and /v1/auth/sign-in refuse it with the usual 401 LOGIN_FAILED. (2) organization is optional, prefilled from the e-mail domain by the rule on SignupRequest.organization. (3) buildingIntent (optional, skippable) records the answer to "What are you building?" and later reads back as ActivationState.buildingIntent. (4) The console session starts on code verification: SignupResult.session carries a TENANT-realm session — the same SessionResponse POST /v1/auth/login answers (15-minute access token, single-use rotating refresh token), for the new admin on the new tenant's site — so a first-party console (its BFF) stores it as it stores a login's session and never needs the password. A brand-new account has no second factor, so there is no MFA step here. Like apiKey, session is a secret in the response body: it is never logged, and the BFF keeps the tokens server-side (httpOnly cookie), never in the page. No session is issued where the tenant admin-MFA policy demands a second factor for the new admin (UAT, PROD), nor when issuing it fails; the tenant and the key exist either way (201). On a rung whose keys are LIVE no key is minted (unchanged). A key handed to an AI agent should be minted actorKind ai from POST /v1/keys; the signup key is not marked AI-channel. SignupResult.accountType echoes the type. For a BUSINESS tenant country is also recorded on the business profile (BusinessProfile.country) and reads back as ActivationState.country, which decides whether the India-only steps of the CAPPED flow are offered. The `business` example below.

Request bodySignupVerifyRequest

  • emailstring · emailRequired
  • codestringRequired
  • passwordstring · passwordOptional
    Optional: the password moves out of signup; the person sets a password later from the console (POST /v1/auth/password/set).Show moreOptional: the password moves out of signup; the person sets a password later from the console (POST /v1/auth/password/set). When sent, the password policy holds (12 to 1024 characters) and the account is created with it, as today.
  • organizationstringOptional
    Optional: absent or blank, prefilled from the e-mail domain by the rule on SignupRequest.organization; sent, 1 to 200 characters.
  • buildingIntentstringOptional
    what the person is building — API_INTEGRATION (calling the API from their own code), AI_AGENT (an AI agent over MCP or the API), BOOKING_SITE (a booking site without code).Show morewhat the person is building — API_INTEGRATION (calling the API from their own code), AI_AGENT (an AI agent over MCP or the API), BOOKING_SITE (a booking site without code). A closed request enum here; the same values read back as the x-extensible-enum ActivationState.buildingIntent, which a client renders tolerantly.
    • API_INTEGRATION
    • AI_AGENT
    • BOOKING_SITE
  • accountTypestringOptional
    what kind of customer a tenant is. BUSINESS is an organisation (the signup before 1.47.0); INDIVIDUAL is one person with no company, whose tenant is named after the person, who verifies with an…Show morewhat kind of customer a tenant is. BUSINESS is an organisation (the signup before 1.47.0); INDIVIDUAL is one person with no company, whose tenant is named after the person, who verifies with an identity check (POST /v1/activation/identity-checks) instead of a business verification and who pays each booking by card through the payment provider's hosted checkout. A tenant created before 1.47.0 reads as BUSINESS. An x-extensible-enum: in a response a client renders the values it knows and treats an unknown one as BUSINESS; in a request a value the server does not know is 400 VALIDATION with details.field accountType.
  • givenNamestringOptional
    the person's given name. Required by the server when accountType is INDIVIDUAL; accepted for BUSINESS (it may be stored on the user).
  • familyNamestringOptional
    the person's family name. Required by the server when accountType is INDIVIDUAL; accepted for BUSINESS (it may be stored on the user).
  • countrystringOptional
    ISO 3166-1 alpha-2 country of the person or the business; optional for both types.Show moreISO 3166-1 alpha-2 country of the person or the business; optional for both types. for a BUSINESS tenant it is also recorded on the business profile (BusinessProfile.country, as PATCH /v1/activation/profile would set it) and reads back as ActivationState.country; it decides whether the India-only steps (GST register look-up, signatory check, GST invoices) are offered.

Responses

  • 201The evaluation tenant, its site, the admin username, and a sandbox key (shown once)SignupResult
  • 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
  • 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
  • 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
  • 429
    Counted in fixed windows (default 15 min).Show moreCounted in fixed windows (default 15 min). The signup, login, password and invite routes count every attempt per client address AND per subject (the email, the username + site, or the invite token). POST /v1/oauth/token is counted three ways, none of them on client_id alone, so knowing a client_id (which is not secret) never lets anyone spend its holder's budget: oauth-token counts every attempt per client address only; oauth-token-failure counts FAILED client authentications per client address and per (client address, client_id) pair; oauth-token-issued counts tokens issued per client_id only, and only a request whose secret, grant_type and scope all passed can spend it. details.reason says which limit tripped (CLIENT_RATE_LIMITED | SUBJECT_RATE_LIMITED) and details.action which count (signup | signup-verify | login | password-forgot | password-reset | invite-accept | oauth-token | oauth-token-failure | oauth-token-issued). Retry-After is whole seconds to the end of the window, and details.retryAfterMs mirrors it. The answer is the same whether or not the account or key exists, so the limit cannot be used to enumerate accounts, and nothing the caller sent is echoed. adds three counts per client address for the MCP grant routes: oauth-authorize (GET /v1/oauth/authorize, which may fetch a Client ID Metadata Document), oauth-register (POST /v1/oauth/register) and oauth-device (POST /v1/oauth/device_authorization), and one count per MCP grant, oauth-exchange-grant (the token exchange of POST /v1/oauth/token, counted per grant after the exchange client and the subject token verified, default 120 a minute), whose details.reason is EXCHANGE_RATE_LIMITED.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501
    NOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug.Show moreNOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug. Also the order read routes (getOrder, listOrderDocuments, listOrderEvents, searchOrders) on a deployment with no order reader assembled; not retryable.
    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
405VALIDATION
This method is not served.
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 requests of this kind for this address or account. Wait for the Retry-After interval before trying again.
retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
seatmap is NOT_APPLICABLE for HTL; GET /v1/capabilities says so
not retryable