agency-board
POST /v1/agency/boards/{boardId}/members
Put somebody on a board, or invite them by email.
Authentication
Send an API key as a bearer token. This endpoint does not state a specific permission in the specification, so give your key the least it needs and check the response rather than assuming.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/agency/boards/{boardId}/members \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "role": <string<manager, member, client>> }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Give `user_id` for somebody who already has an account, or `email` to invite somebody who does not — the invitation goes through `tenancy.Invitation` and the person joins on acceptance, authenticated by Keycloak with no secret token in the flow. ⛔ A `client` seat may only be given to a member of the board's own client organisation, and **no seat is written for a pending invite**: a client's authorisation is a live membership of that organisation, re-read on every request, so a seat created before acceptance would look like access and confer none.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
boardId (path) | Uuid | Yes | Project board ID (UUIDv7). |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
user_id | string | No | Somebody who already has an account. Give this **or** `email`, not both. |
email | string | No | Invite somebody who does not have an account yet. |
role | string<manager, member, client> | Yes | — |
member_org_id | string | No | Which organisation this seat belongs to. Ignored for a `client` seat, which is always the board's own client organisation. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
id | Uuid | Yes | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
board_id | Uuid | Yes | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
user_id | Uuid | Yes | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
member_org_id | Uuid | Yes | The organisation this seat belongs to — the agency's, or the client's. |
role | string<manager, member, client> | Yes | — |
last_read_at | string | No | — |
created_at | string | No | — |
user | AgencyBoardActor | No | Who holds this seat, by name. ⛔ Render THIS, never `user_id` — the People drawer printed the id at a colleague's name until 2026-09-01 (`docs/425`). |
invited_by | AgencyBoardActor | No | — |
Errors this endpoint can return
401 · 403 · 404 · 422