Look up business registration by number

POST/v1/activation/business-registrations:look-up

Accepts bearer

Look a business registration up by country and number — GSTIN, company number, trade licence, EIN, BN

Reads the registration a number names from the country's register and answers it for the person to confirm (POST /v1/activation/business-registration:confirm with scheme and number); nothing is stored. A read sent as POST so the number and the legal name stay out of the URL and the access logs. country picks the scheme: IN IN_GSTIN (the GST register, as GET /v1/activation/business-registrations/{gstin}, which stays), GB GB_COMPANY_NUMBER (the companies register), AE AE_TRADE_LICENCE (the licensing authority's register; jurisdiction names the emirate or free zone), US US_EIN (the IRS name and EIN match: legalName is required, 400 VALIDATION details.field legalName otherwise, and status reads ACTIVE when the name matches the EIN, else NOT_MATCHED; the IRS states no address and no registration date) and CA CA_BUSINESS_NUMBER (the federal business registry). The answer carries scheme, number and jurisdiction; gstin and pan are set on the India path only, and constitution, registeredOn and address only where the register states them. status is x-extensible-enum (ACTIVE, CANCELLED, SUSPENDED, DISSOLVED, EXPIRED, NOT_MATCHED): a registration that is not ACTIVE is answered (200) so the screen can say why, and confirming it is refused. country must be one of IN, GB, AE, US or CA and equal the tenant's country (ActivationState.country), else 400 VALIDATION details.field country; a number that does not match the scheme's format is 400 VALIDATION details.field number. A well-formed number the register does not know is 404 NOT_FOUND details.reason REGISTRATION_NOT_FOUND (an India GSTIN keeps GSTIN_NOT_FOUND). The capped flow off is 501 NOT_IMPLEMENTED details.reason CAPPED_FLOW_UNAVAILABLE; no register provider for the country is 501 details.reason REGISTER_UNAVAILABLE (GST_REGISTER_UNAVAILABLE for IN); 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 GSTIN look-up.

Request bodyBusinessRegistrationLookup

countrystringRequired
ISO 3166-1 alpha-2, one of IN (IN_GSTIN), GB (GB_COMPANY_NUMBER), AE (AE_TRADE_LICENCE), US (US_EIN) or CA (CA_BUSINESS_NUMBER); the tenant's own country
numberstringRequired
The number as issued. IN a 15-character GSTIN; GB an 8-character company number (it may start with two letters, as SC or NI); AE the trade licence number; US the nine-digit EIN, with or without the…Show more
The number as issued. IN a 15-character GSTIN; GB an 8-character company number (it may start with two letters, as SC or NI); AE the trade licence number; US the nine-digit EIN, with or without the hyphen after the second digit; CA the nine-digit business number (the root BN)
legalNamestringOptional
Required for US (the IRS name and EIN match); not read for the other countries

Responses

200The registration as the register states itBusinessRegistration
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 more
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 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 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 — 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 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
413
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.
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
415
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.
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 more
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 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 more
UPSTREAM_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.

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
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 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