Invite a staff member to the firm

POST/api/v1/advisory-firms/{firm_id}/users/invite

Invite a user by email to join the firm as staff (admin or member). If the user already exists they are added immediately; otherwise an invitation email is sent and they are added on signup. Owner role cannot be assigned via invitation.

Operation ID: invite_staff_to_firm·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Parameters

Path

firm_idstringrequired

Request body

Schema: InviteStaffRequest

emailstringrequired

Email address of the person to invite.

rolestring

Role to assign: 'admin' or 'member'. Owner cannot be invited.

One of: admin, member

first_namestring

Optional first name to personalize the invitation.

last_namestring

Optional last name to personalize the invitation.

messagestring

Optional personal message from the inviter included in the email.

business_idsarray · string

For 'member' role: explicit list of businesses the invitee should be assigned to on acceptance. Ignored for 'admin' (admins see every firm business).

team_idstring

For 'member' role: team to add the invitee to on acceptance. Mutually exclusive with 'business_ids' and 'assign_all_firm_businesses'.

assign_all_firm_businessesboolean

For 'member' role: if true, grant the invitee direct assignment to every currently active firm business on acceptance.

Responses

201Successful Response

Schema: SuccessEnvelope_InviteStaffResponse_

successboolean
messagestring
codestring
dataInviteStaffResponse

400Bad Request - Invalid input

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

401Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

403Forbidden - Insufficient permissions

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

409Conflict - Resource already exists or is in an incompatible state

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

422Validation Error

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

Code samples

POST/api/v1/advisory-firms/{firm_id}/users/invite

bash

curl -X POST 'https://api.ondayzero.com/api/v1/advisory-firms/{firm_id}/users/invite' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "business_ids": [
    "b1111111-1111-1111-1111-111111111111"
  ],
  "email": "staff@example.com",
  "role": "member"
}'