API reference
API access and permissions
An integration's access has two parts: where it can work (the workspace or one inbox) and what it can do (its permissions). Both are enforced when data is requested and before queued events are delivered.
Choose workspace or one inbox
| Connection scope | Who can set it up | Connection type and activity |
|---|---|---|
| Entire workspace | Workspace Owners only | Company connection; eligible external calls and messages across all current and future shared and personal inboxes. |
| One shared inbox | Workspace Owners and Admins | Company connection; eligible activity within that shared inbox. |
| One shared inbox | A workspace Member with the Manager role in that inbox | Personal connection; eligible activity within that shared inbox while the person remains authorized. |
| Own personal inbox | The teammate who owns the inbox, including an Owner or Admin | Personal connection; eligible activity within their personal inbox. |
Company connections continue independently of the person who installed them. Personal connections depend on that person remaining active and retaining the required inbox access. Being a shared-inbox Viewer or Member does not let a workspace Member create a connection for that inbox; they need its Manager role. Management actions also depend on the connection's scope: only an Owner can configure an entire-workspace connection. Revocation stops access for any connection.
Older connections may retain a previous inbox selection. They are not automatically upgraded to workspace access. Create a replacement connection to change permissions or scope, switch your application to its key, and delete the old connection.
Contact visibility stays intact
Workspace connections read and sync workspace-visible contacts only. Contacts restricted to a shared inbox or a personal inbox remain restricted and are excluded from workspace contact access. Connecting all inbox activity does not make those contacts workspace-visible.
An inbox connection follows its authorized contact access. New contacts created by a workspace connection are workspace contacts; new contacts created by an inbox connection are shared with that inbox. Personal-inbox contacts are owned by the subject member. Updating an existing contact preserves its audience. Source-managed read-only contacts cannot be changed by the API.
Call and message visibility
A workspace connection reads one call with its complete journey. An inbox connection sees only its inbox's interactions, grouped into one call entry. Transfers that return to the same inbox do not create duplicate calls. The same call ID can appear in different inbox feeds, so store your connection or inbox context alongside that ID when combining them.
The call.completed event is sent when the overall external call ends. An inbox's own interaction can end earlier. Completion does not guarantee that a recording, saved transcript, or summary is ready. Use the corresponding readiness events described in Webhooks when your workflow needs that content.
Internal-only calls and messages are excluded. A message involving external participants is available only when the connection is authorized for every inbox in its conversation. Mixed conversations do not bypass that rule. A message's external_numbers lists external conversation participants; do not treat it as confirmation that each participant received that message.
Recording and attachment endpoints apply additional resource-access checks. A visible call or message does not automatically grant access to every associated media file. Fetch downloads through the dedicated endpoints and treat their temporary URLs as private.
Grant only the permissions you need
| Permission | Use |
|---|---|
contacts.read | Read accessible contacts, notes, and existing property values. |
contacts.write | Create or update accessible contacts, notes, and property values; also requires contacts.read. |
calls.read | Read eligible calls and authorized recording details, saved transcripts, and summaries. |
messages.read | Read eligible messages and authorized attachment details. |
messages.write | Send billed messages and prepare uploads; also requires messages.read. |
inboxes.read | List the connection's currently authorized inboxes. |
phone_numbers.read | Read phone numbers and their status in authorized inboxes; entire-workspace access also includes unassigned numbers. |
analytics.read | Read external-call totals, outcomes, and trends for authorized inboxes. |
webhooks.read | Inspect this connection's subscriptions and delivery history. |
webhooks.write | Manage subscriptions; event subscriptions also require their resource's read permission. |
The endpoint reference describes each operation's exact requirements. A valid key with insufficient permissions receives 403; a resource outside its access may appear as 404.
GET /v1/members returns 403 for API keys and service connections, even when they have inboxes.read. To look up teammates with an assistant, use Waveline's supported assistant connection. Do not copy an assistant token into a REST request; those credentials are authorized for the assistant connection.
API keys and connected apps
New API keys created in Waveline do not expire on a timer. Their access still ends when the connection is revoked or no longer authorized. Keys are shown once. Store them securely and replace them when necessary.
OAuth connections also have no scheduled expiration for new grants. Their short-lived access tokens last 15 minutes and the client refreshes them using rotating refresh tokens. An expired access token does not mean the integration itself expired. OAuth credentials remain bound to the resource authorized during consent; assistant/MCP tokens cannot be substituted for REST API credentials.
Deleting an integration stops its access and removes it from the list. Existing contacts, messages, activity, and billing records are preserved. Requests already in flight and messages already accepted for sending cannot be recalled by deleting the connection.