Look up business registration

GET/v1/activation/business-registrations/{gstin}

Accepts bearer

Look a GSTIN up in the GST register — proposed rail step business_verification

Reads the registration a GSTIN names from the GST register and answers it for the person to confirm: legal and trade name, constitution, status, registration date, the company PAN and the principal place of business. Nothing is stored by the look-up; POST /v1/activation/business-registration:confirm stores it. India only: a tenant whose country (SignupVerifyRequest.country or BusinessProfile.country) is not IN, or not yet set, is 400 VALIDATION details.reason INDIA_ONLY_FIELD; a GSTIN that does not match the pattern is 400 VALIDATION details.field gstin. A well-formed GSTIN the register does not know is 404 NOT_FOUND details.reason GSTIN_NOT_FOUND. A CANCELLED or SUSPENDED registration is answered (200) so the screen can say why it cannot be used; confirming it is refused. status and constitution are x-extensible-enum. The capped flow off, or no provider configured, is 501 NOT_IMPLEMENTED (details.reason CAPPED_FLOW_UNAVAILABLE or GST_REGISTER_UNAVAILABLE); a provider that cannot be reached is 502 UPSTREAM_UNAVAILABLE (retryable). Human session only (an API key is 403 PERMISSION_DENIED details.reason SESSION_REQUIRED); needs users:manage, as the profile it fills.

Path parameters

gstinstringRequired
India GSTIN, 15 characters, upper case

Request body

This operation takes no request body.

Responses

200The registration as the GST register states itBusinessRegistration
400
VALIDATION on the GST registration routes: details.reason INDIA_ONLY_FIELD when the tenant's country is not IN (or not yet set), or details.field gstin when the GSTIN does not match the 15-character…Show more
VALIDATION on the GST registration routes: details.reason INDIA_ONLY_FIELD when the tenant's country is not IN (or not yet set), or details.field gstin when the GSTIN does not match the 15-character pattern.
ApiErrorResponse
401
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.
ApiErrorResponse
403ApiErrorResponse
404NOT_FOUND GSTIN_NOT_FOUND — the GST register has no registration for this GSTINApiErrorResponse
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 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.
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 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.
ApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
501Not retryable.ApiErrorResponse
502
UPSTREAM_UNAVAILABLE — the GST register provider could not be reached.Show more
UPSTREAM_UNAVAILABLE — the GST register provider could not be reached. Nothing was stored; the rail shows step business_verification blocked until it answers.
ApiErrorResponse

Errors you should handle

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

400	VALIDATION A GSTIN can be used only for a business in India.	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
404	NOT_FOUND The GST register has no registration for 29AABCS9999F1Z5.	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
501	NOT_IMPLEMENTED The capped activation flow is not available on this deployment.	not retryable
502	UPSTREAM_UNAVAILABLE The GST register is not answering right now. Try again in a minute.	retryable