Scopes
Permissions you can request during the OAuth flow.
When you start the OAuth flow at /oauth-authorize, pass a space‑separated list of scopes. Request the minimum scopes your integration needs. The same scope strings apply to API keys (configured when you create the key in the dashboard).
Available scopes
| Field | Type | Description |
|---|---|---|
contacts:read | scope | Read contacts, deals, activities, and search. Required by GET /api-deals, GET /api-activities, and POST /api-contacts-search. GET /api-contacts and its sub-resources (/:id, /:id/deals, /:id/activities) only require a valid credential — no explicit scope check. |
contacts:write | scope | Create, update, and delete contacts. Required by POST /api-contacts, PATCH /api-contacts/:id, and DELETE /api-contacts/:id. |
webhooks:read | scope | Required by every /api-webhook-subscriptions request — including POST and DELETE, which additionally require webhooks:write. Covers GET /api-webhook-subscriptions and GET /api-webhook-subscriptions/:id on its own. |
webhooks:write | scope | Required in addition to webhooks:read for POST /api-webhook-subscriptions and DELETE /api-webhook-subscriptions/:id. webhooks:write alone is not sufficient — the endpoint checks webhooks:read first. |
Example
text
scope=contacts:read%20contacts:write%20webhooks:writeA Zapier‑style integration that lists contacts, creates contacts, and subscribes to triggers typically needs contacts:read contacts:write webhooks:read webhooks:write.
Scope errors
Calling an endpoint without the required scope returns HTTP 403:
json
{
"error": "forbidden",
"message": "Scope 'contacts:write' is required."
}