Skip to content

Team members

The people with a login to your Bookline portal and their access, and how to change or remove that access.

The team members endpoints return the people with a login to your account’s portal and their access to it, and let you change or remove that access. Reading needs users:read; changing needs users:write.

Endpoint Route Scope
List team members GET /v1/users users:read
One team member GET /v1/users/{user_id} users:read
Replace a team member’s access PATCH /v1/users/{user_id} users:write
Remove a team member DELETE /v1/users/{user_id} users:write

The team belongs to the whole customer: a key limited to some venues gets 403 insufficient_scope. In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.

GET /v1/users returns your team, paged. Takes limit (1 to 100, default 50), cursor and customer_id.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/users"
{
"data": [
{
"id": "…",
"name": "Ana García",
"email": "ana@example.com",
"access": [
{ "level": "ADMIN", "resource": "ALL", "venue_ids": [] }
]
}
],
"meta": { "limit": 50, "next_cursor": null }
}
Field What it is
id The team member’s identifier
name Their name
email The address they log in with
access[] Their access to this customer only, one entry per grant
access[].level What they may do: ADMIN, VIEW, CREATE, UPDATE or DELETE
access[].resource What it covers: ALL of the customer, some VENUES, or only BOTS, ACCOUNTS or ACTIVITY (metrics, calls and chats)
access[].venue_ids The venues it covers when resource is VENUES; empty otherwise

Bookline’s own team does not appear. A partner of yours (an agency or integrator) with access to your account does.

GET /v1/users/{user_id} returns the same fields, with an ETag header: the version to send as If-Match when you change their access. Someone without access to your account is 404 not_found.

PATCH /v1/users/{user_id} replaces the person’s ALL, VENUES and ACTIVITY grants on your account with the list you send. Send their ETag as If-Match (see Writing data).

Field Rules
access 1 to 20 grants
access[].level ADMIN, VIEW, CREATE, UPDATE or DELETE
access[].resource ALL, VENUES or ACTIVITY
access[].venue_ids Live venues of your account: required when resource is VENUES (up to 200), not allowed otherwise
Ventana de terminal
curl -s -X PATCH "$BASE/users/<user_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "<etag>"' \
-d '{"access": [{"level": "VIEW", "resource": "VENUES", "venue_ids": ["<venue_id>"]}]}'
  • BOTS and ACCOUNTS grants are set in the portal only: leave them out and they are kept.
  • Their access to other Bookline accounts is never read nor changed.
  • Only existing team members: inviting someone new is done in the portal (an unknown id is 404 not_found).
  • The answer is the team member as stored, with their new ETag. It is personal data: it counts in the 30-per-minute limit and is recorded like a read.

DELETE /v1/users/{user_id} removes the person’s ALL, VENUES and ACTIVITY grants on your account. Send their ETag as If-Match. The answer is 204.

BOTS and ACCOUNTS grants, set in the portal only, stay; someone left with none is no longer a team member. The person’s login and their access to other accounts stay.

Both writes follow these rules, on top of the users:write scope:

Rule Answer otherwise
The key must be an account key, or the key of one of your own users who holds ADMIN on ALL of the account 403 insufficient_scope
A key never changes its own owner’s access 403 insufficient_scope
A partner’s access (an agency or integrator) is set by Bookline 403 insufficient_scope
The account keeps at least one of its own users with ADMIN on ALL 409 conflict
Every venue_ids entry is a live venue of the account 422 validation_failed

The message of each refusal explains it; see why a write can be refused.

  • The version covers the whole person. A change to their access on another Bookline account, or to their profile, also changes their ETag: a write then answers 412. Read them again and resend.
  • Their API keys follow their new access. A team member’s keys are not revoked: they act with the person’s current access, so narrowed access applies to their keys within about a minute.