Invite a user
POST/v1/businesses/{businessId}/users
Invites a user to the business with the role you supply, and sends them a welcome email so they can set their password and sign in to the Hiya Console.
A person belongs to one business at a time. If the email already
belongs to a user, the request is rejected with 409 — unless that
user is on another of your businesses and you pass force=true, in
which case they are moved here:
| The email belongs to … | force=false (default) | force=true |
|---|---|---|
| nobody yet | 201 — user invited | 201 — user invited |
| a user on this business | 409 | 409 |
| a user on another of your businesses | 409 | 200 — user moved here |
| any other Hiya user | 409 | 409 |
Moving a user takes them off the other business, so they lose access
to it. Their name and role are set to the ones you send, and they get
a new welcome email. A user who isn't on one of your businesses is
never moved, whatever force says.
The business must have completed verification (ACTIVE or
INACTIVE); one still UNDER_REVIEW or in NEEDS_ATTENTION, or one
being shut down, returns 409. When moving a user, so does a source
business that is being shut down.
Path Parameters
The ID of the business, assigned by Hiya.
9b8a1c4e-2c0f-4f3d-9a1e-7b3a2b4c6d8fQuery Parameters
Move the user onto this business if the email belongs to a user on another of your businesses. Without it, that case returns
409
falseHeader Parameters
Your own correlation ID for this call, returned as
requestId
400
INVALID_HEADER
Possible values: <= 200 characters, Value must match regular expression ^[A-Za-z0-9._:/+=@-]+$
job-2f9c1a7e-0042Body
required
Responses
- 200
- 201
- 400
- 401
- 404
- 409
- 500
force=true was passed and the email belonged to a user on another
of your businesses. The user was moved onto this business. Returns
the user.
Response Body
User invited. Returns the new user.
Response Body
The request is invalid — a missing required field, a field that
fails validation (such as a malformed email or an unknown
role), a force that isn't true or false, or an
X-Hiya-Request-Id header that doesn't match its pattern.
Response Body
The API key is missing or invalid.
Response Body
No business with that ID exists, or it isn't one of yours — the two are indistinguishable by design.
Response Body
The user can't be invited. Returned as CONFLICT, the same code
for every case — the message says which applies:
| Message | Case |
|---|---|
The business hasn't completed verification. | The business is UNDER_REVIEW or NEEDS_ATTENTION. |
The business is being shut down. | This business, or the one a user would be moved from, is being deleted. |
A user with this email is already on this business. | Nothing to invite. |
A user with this email is on another of your businesses. Pass force=true to move them to this business. | Only returned without force=true. |
This email belongs to a Hiya user who can't be moved to this business. | Returned with or without force. |
Response Body
Something went wrong on our side.
Response Body