Create a business

POST 
/v1/businesses

Creates a business and starts verification. The new business starts in status UNDER_REVIEW. Poll GET /v1/businesses/{businessId} to see when its status changes.

Header Parameters

---

X-Hiya-Request-Id string
Your own correlation ID for this call, returned as
requestId
in the response body. Hiya generates one if omitted. A value that doesn't match the pattern is rejected with
400
INVALID_HEADER
.
Possible values: <= 200 characters, Value must match regular expression ^[A-Za-z0-9._:/+=@-]+$
Example: job-2f9c1a7e-0042

Body

required

application/json

Responses

201

Business created and submitted for verification.

Response Body

application/json

400

The request is invalid — a missing required field, a field that fails validation (such as a missing address.region for a US business, or an invalid contact email or phone), or an X-Hiya-Request-Id header that doesn't match its pattern.

Response Body

application/json

401

The API key is missing or invalid.

Response Body

application/json

409

An externalId was supplied and one of your businesses already uses it. externalId is unique per partner, so this never reflects another partner's business.

Returned as CONFLICT, the same code as the other 409 cases — the message distinguishes them.

Response Body

application/json

500

Something went wrong on our side.

Response Body

application/json