Scopes

Understand API key permissions and scopes

Overview

Scopes define what operations an API key can perform. When creating an API key, you assign specific scopes to limit its access to only the resources it needs.

Principle of least privilege: Always assign the minimum scopes required for your integration to function.

Available Scopes

Contacts

Scope	Description
contacts:read	List and retrieve contact details
contacts:write	Create, update, and delete contacts
contacts:*	All contact permissions

Endpoints:

• GET /api/v1/contacts - requires contacts:read
• POST /api/v1/contacts - requires contacts:write
• GET /api/v1/contacts/:id - requires contacts:read
• PATCH /api/v1/contacts/:id - requires contacts:write
• DELETE /api/v1/contacts/:id - requires contacts:write

Surveys

Scope	Description
surveys:read	List and retrieve survey details
surveys:write	Create, update, and delete surveys
surveys:send	Trigger survey sends to contacts
surveys:*	All survey permissions

Endpoints:

• GET /api/v1/surveys - requires surveys:read
• POST /api/v1/surveys - requires surveys:write
• GET /api/v1/surveys/:id - requires surveys:read
• PATCH /api/v1/surveys/:id - requires surveys:write
• DELETE /api/v1/surveys/:id - requires surveys:write

Sequences

Scope	Description
sequences:read	List and retrieve sequence details
sequences:execute	Trigger sequences for contacts
sequences:*	All sequence permissions

Endpoints:

• GET /api/v1/sequences - requires sequences:read
• GET /api/v1/sequences/:id - requires sequences:read
• POST /api/v1/sequences/:id/execute - requires sequences:execute

Responses

Scope	Description
responses:read	List and retrieve survey responses
responses:*	All response permissions

Endpoints:

• GET /api/v1/responses - requires responses:read
• GET /api/v1/responses/:id - requires responses:read

Reviews

Scope	Description
reviews:read	List and retrieve customer reviews
reviews:write	Create and update review replies
reviews:*	All review permissions

Endpoints:

• GET /api/v1/reviews - requires reviews:read
• GET /api/v1/reviews/:id - requires reviews:read
• POST /api/v1/reviews/:id/reply - requires reviews:write
• PATCH /api/v1/reviews/:id/reply - requires reviews:write

Webhooks

Scope	Description
webhooks:read	List and retrieve webhook configurations
webhooks:write	Create, update, and delete webhooks
webhooks:*	All webhook permissions

Admin

Scope	Description
admin	Full access to all resources (use sparingly)

The admin scope grants unrestricted access to your entire organization’s data. Only use this for internal tools or trusted integrations.

Wildcard Scopes

You can use wildcards to grant all permissions for a resource:

• contacts:* - All contact operations (read + write)
• surveys:* - All survey operations (read + write + send)
• sequences:* - All sequence operations (read + execute)

Scope Checking

When an API key doesn’t have the required scope, you’ll receive:

Status: 403 Forbidden

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This API key does not have the required scope: contacts:write",
    "requiredScope": "contacts:write",
    "availableScopes": ["contacts:read", "surveys:read"]
  }
}

Common Scope Combinations

Read-only analytics integration

For dashboards that display metrics but don’t modify data:

["responses:read", "reviews:read", "contacts:read"]

CRM sync integration

For two-way contact synchronization with your CRM:

["contacts:read", "contacts:write", "responses:read"]

Marketing automation

For triggering surveys and sequences based on customer actions:

["contacts:write", "sequences:execute", "responses:read"]

Review management tool

For monitoring and responding to customer reviews:

["reviews:read", "reviews:write"]

Next Steps

Authentication

Learn how to create API keys

Quick Start

Make your first API call