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

Confirm business registration

POST/v1/activation/business-registration:confirm
Idempotency-Key requiredAccepts bearer

Confirm the looked-up registration; it fills the business profile

Re-reads the GSTIN from the register (never trusts a client copy) and, when its status is ACTIVE, stores it on the business profile: legalName, address, gstin and pan (the company PAN), with country…Show moreRe-reads the GSTIN from the register (never trusts a client copy) and, when its status is ACTIVE, stores it on the business profile: legalName, address, gstin and pan (the company PAN), with country IN and gstinConfirmedAt. Under the CAPPED flow this completes rail step business_profile (BusinessProfile.complete true) and opens the signatory check (POST /v1/activation/signatory-checks), which completes step business_verification. A registration that is not ACTIVE is 409 CONFLICT details.reason GSTIN_NOT_ACTIVE (details.status names it) and nothing is stored. A GSTIN already confirmed by ANOTHER tenant is 409 CONFLICT details.reason GSTIN_ALREADY_CLAIMED and nothing is stored; that business verifies through the hosted KYB session (POST /v1/activation/verification-sessions). Confirming the GSTIN already confirmed is a 200 with the profile as stored. Confirming a different GSTIN replaces the confirmed one: before the tenant is LIVE only an Owner may do it (403 PERMISSION_DENIED details.reason OWNER_ONLY otherwise) and it clears the signatory check, so step business_verification needs the check again; once the tenant is LIVE it is 409 CONFLICT details.reason REGISTRATION_LOCKED (an ops change). Errors as the look-up (400 INDIA_ONLY_FIELD, 404 GSTIN_NOT_FOUND, 501, 502). Human session only; needs users:manage (the Owner to replace). Idempotency-Key required. Audited (activation.registration_confirmed). the body carries exactly one of gstin (the India path above) or scheme with number (a registration POST /v1/activation/business-registrations:look-up answered: IN_GSTIN, GB_COMPANY_NUMBER, AE_TRADE_LICENCE, US_EIN or CA_BUSINESS_NUMBER; for US_EIN also legalName, as the look-up); neither, both, or a scheme without a number is 400 VALIDATION details.field gstin (the backend enforces it, no oneOf). The register is re-read and the confirmed registration is stored on the profile (legalName, address when the register states it, registrationScheme, registrationNumber, and businessStructure from the register's legal form when the profile has none); ActivationState.registrationConfirmedAt is set for every scheme, registrationGstin and gstinConfirmedAt for IN_GSTIN only. A status other than ACTIVE is 409 CONFLICT details.reason GSTIN_NOT_ACTIVE and a number another tenant confirmed is 409 GSTIN_ALREADY_CLAIMED, for every scheme (the 1.51.0 reasons are kept so a client branches once; details.status names the status). An unknown number is 404 REGISTRATION_NOT_FOUND; no provider for the country is 501 REGISTER_UNAVAILABLE. On the CAPPED rail of 1.63.0 the confirm no longer completes business_profile by itself (GET /v1/activation): it completes the registration part of business_verification.

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 bodyBusinessRegistrationConfirmRequest

  • gstinstringOptional
  • schemestringOptional
    the scheme the look-up by number answered
  • numberstringOptional
    the number the look-up by number answered
  • legalNamestringOptional
    with US_EIN, the legal name the IRS matches (as the look-up)

Responses

  • 200The business profile as stored, filled from the registrationBusinessProfile
  • 400
    VALIDATION on the business registration routes: as GstinValidation (INDIA_ONLY_FIELD, the GSTIN pattern), plus details.field country (a country not served, or not the tenant's), number (not the…Show moreVALIDATION on the business registration routes: as GstinValidation (INDIA_ONLY_FIELD, the GSTIN pattern), plus details.field country (a country not served, or not the tenant's), number (not the scheme's format), legalName (missing on a US EIN look-up) and gstin (the confirm with neither or both of gstin and scheme with number).
    ApiErrorResponse
  • 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
  • 404NOT_FOUND — the register has no registration for the number: details.reason REGISTRATION_NOT_FOUND, or GSTIN_NOT_FOUND for an India GSTIN (as GstinNotFound).ApiErrorResponse
  • 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
  • 409
    CONFLICT GSTIN_NOT_ACTIVE (the registration is not ACTIVE), GSTIN_ALREADY_CLAIMED (another tenant confirmed this GSTIN; use hosted KYB) or REGISTRATION_LOCKED (the tenant is LIVE; replacing the GSTIN…Show moreCONFLICT GSTIN_NOT_ACTIVE (the registration is not ACTIVE), GSTIN_ALREADY_CLAIMED (another tenant confirmed this GSTIN; use hosted KYB) or REGISTRATION_LOCKED (the tenant is LIVE; replacing the GSTIN is an ops change); or IDEMPOTENCY_CONFLICT
    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
  • 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
A GSTIN can be used only for a business in India.
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
404NOT_FOUND
The GST register has no registration for 29AABCS9999F1Z5.
not retryable
405VALIDATION
This method is not served.
not retryable
409CONFLICT
GSTIN 29AABCS0000F1Z5 is CANCELLED in the GST register and cannot verify the business.
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
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