Scopes
A key can do only what its scopes allow. Write scopes do not include read: a key that adds contacts and then reads them needs both.
| Scope | Allows | Endpoints |
|---|---|---|
contacts:read | Read contacts. | GET /contacts, GET /contacts/{id}, POST /contacts/search, GET /custom-fields |
contacts:write | Add contacts and change them. | POST /contacts, PATCH /contacts/{id}, DELETE /contacts/{id}, POST /contacts/upsert |
companies:read | Read companies. | GET /companies, GET /companies/{id}, POST /companies/search, GET /custom-fields |
companies:write | Add companies and change their owner and tags. | POST /companies, PATCH /companies/{id} |
deals:read | Read deals. | GET /deals, GET /deals/{id}, POST /deals/search, GET /pipelines, GET /custom-fields |
deals:write | Create deals, change them and move them between stages. | POST /deals, PATCH /deals/{id}, DELETE /deals/{id}, POST /deals/{id}/move |
reports:read | Read the revenue report. | GET /reports/revenue |
team:read | Read the teammates in the workspace (seats), to resolve owners and assign work. | GET /seats |
activity:read | Read timelines and tasks. | GET /contacts/{id}/timeline, GET /companies/{id}/timeline, GET /deals/{id}/timeline, GET /notes, GET /tasks, GET /tasks/{id} |
activity:write | Add notes, and create, finish and reschedule tasks. | POST /notes, POST /tasks, PATCH /tasks/{id} |
lists:read | Read lists and who is in them. | GET /lists, GET /lists/{id}, GET /lists/{id}/members |
lists:write | Add people to lists and take them out. | POST /lists/{id}/members, POST /lists/{id}/members/remove |
outreach:write | Enrol contacts in live weaves and active sequences. Spends credits, as enrolling in Workloom does. | GET /outreach, POST /weaves/{id}/enrol, POST /sequences/{id}/enrol |
webhooks:manage | Add, change and remove webhook endpoints, and resend deliveries. A webhook sends every record its events name to an address of your choosing, so give this only to what needs it. | POST /sandbox/events, GET /webhooks, POST /webhooks, GET /webhooks/{id}, PATCH /webhooks/{id}, DELETE /webhooks/{id}, POST /webhooks/{id}/rotate-secret, GET /webhooks/{id}/secret, POST /webhooks/{id}/test, GET /webhooks/{id}/deliveries, POST /webhooks/{id}/deliveries/{delivery_id}/resend |
creative:read | Read documents and templates. | GET /documents |
creative:write | Make documents from templates, export PDFs, edit videos and make designs, with the checks the app runs. | POST /documents, POST /documents/{id}/export, POST /videos/{id}/edit, POST /designs |
A key that acts for one person also reaches only what that person’s role reaches. Scopes say which kinds of record a key may touch; the role says which records.
When a scope is missing
You get a 403 with code missing_scope, the scope the call needed and the scopes the key has.
Response
{
"error": "This key does not have the \"deals:write\" scope.",
"code": "missing_scope",
"required": [
"deals:write"
],
"granted": [
"contacts:read",
"deals:read"
]
}403 Forbidden
GET / and GET /events need no scope, so you can always check what a key holds.
Was this page useful?