> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/staff.md).

# Staff

The workroom's users — sales reps, admins, and AI agents. Read-only; invite staff from the dashboard. Every `usr_...` reference on tasks, appointments, conversations, and sales automations resolves to a staff record.

## GET /staff

> List staff (workroom users).

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Staff","description":"The workroom's users — sales reps, admins, AI agents. Read-only from v3; admin invites happen in the dashboard. Every `usr_<hex>` reference on tasks / appointments / conversations / sales_automations resolves to a Staff record."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Staff":{"type":"object","description":"A workroom user — sales rep / admin / support. Read-only in v3. Never includes password, access_token, or other credentials.\n","properties":{"id":{"$ref":"#/components/schemas/StaffId"},"object":{"type":"string","enum":["staff"]},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true,"description":"IANA tz string (e.g. `America/Chicago`)."},"type":{"type":"string","enum":["primary","secondary"],"nullable":true,"description":"`primary` is the account owner; `secondary` are invited team members."},"status":{"type":"string","enum":["active","inactive"]},"role":{"type":"string","nullable":true,"description":"Custom role name (`userrole` field). Null when using default permissions."},"is_default":{"type":"boolean","description":"True for the default responsible user in the workroom."},"priority":{"type":"integer","nullable":true,"description":"Round-robin / load-balancing priority. Lower = tried first."},"workroom_ids":{"type":"array","items":{"$ref":"#/components/schemas/WorkroomId"},"description":"Workrooms this staff member can access."},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_login_at":{"$ref":"#/components/schemas/Timestamp"},"last_login_type":{"type":"string","nullable":true,"description":"`web`, `mobile`, etc."}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/staff":{"get":{"tags":["Staff"],"operationId":"listStaff","summary":"List staff (workroom users).","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","inactive"]},"type":{"type":"string","enum":["primary","secondary"]},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"q":{"type":"string","description":"Case-insensitive substring match on name OR email."}}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Staff"}}}}]}}}}}}}}}
```

## Retrieve one staff user.

> A workroom staff member's profile — name, email, role and workroom access. Credentials and access tokens are never returned.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Staff","description":"The workroom's users — sales reps, admins, AI agents. Read-only from v3; admin invites happen in the dashboard. Every `usr_<hex>` reference on tasks / appointments / conversations / sales_automations resolves to a Staff record."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"Staff":{"type":"object","description":"A workroom user — sales rep / admin / support. Read-only in v3. Never includes password, access_token, or other credentials.\n","properties":{"id":{"$ref":"#/components/schemas/StaffId"},"object":{"type":"string","enum":["staff"]},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true,"description":"IANA tz string (e.g. `America/Chicago`)."},"type":{"type":"string","enum":["primary","secondary"],"nullable":true,"description":"`primary` is the account owner; `secondary` are invited team members."},"status":{"type":"string","enum":["active","inactive"]},"role":{"type":"string","nullable":true,"description":"Custom role name (`userrole` field). Null when using default permissions."},"is_default":{"type":"boolean","description":"True for the default responsible user in the workroom."},"priority":{"type":"integer","nullable":true,"description":"Round-robin / load-balancing priority. Lower = tried first."},"workroom_ids":{"type":"array","items":{"$ref":"#/components/schemas/WorkroomId"},"description":"Workrooms this staff member can access."},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_login_at":{"$ref":"#/components/schemas/Timestamp"},"last_login_type":{"type":"string","nullable":true,"description":"`web`, `mobile`, etc."}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/staff/{id}":{"get":{"tags":["Staff"],"operationId":"retrieveStaff","summary":"Retrieve one staff user.","description":"A workroom staff member's profile — name, email, role and workroom access. Credentials and access tokens are never returned.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Staff"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
