Waveline API reference

The API uses Bearer authentication at https://api.waveline.tel. Start with the quickstart to create a scoped API key.

This reference is generated from the Waveline OpenAPI contract. Download the OpenAPI specification for use with your API client or code generator.

Check each operation's authentication and permission requirements. In particular, GET /v1/members is not available to REST API keys or service connections. Teammate lookup is available through Waveline’s supported assistant connection; do not send an assistant token to the REST API. See API access and permissions before choosing credentials.

Endpoints

Connection, inboxes, and teammates

• GET /v1/connection — Test API credentials and inspect their scope
• GET /v1/members — List teammates in accessible inboxes
• GET /v1/inboxes — List the connection's allowed inboxes

Contacts

• GET /v1/contacts — List or find accessible contacts
• POST /v1/contacts — Create a contact
• POST /v1/contacts/upsert — Create or update a contact by external identity
• GET /v1/contacts/{id} — Get one accessible contact
• PATCH /v1/contacts/{id} — Update selected fields of an accessible contact
• GET /v1/contacts/{id}/notes — List contact notes
• POST /v1/contacts/{id}/notes — Add a contact note
• PATCH /v1/contacts/{id}/notes/{note_id} — Update a contact note
• DELETE /v1/contacts/{id}/notes/{note_id} — Soft-delete a contact note
• GET /v1/contact-properties — List existing workspace contact property definitions
• GET /v1/contacts/{id}/properties — List contact property values
• PATCH /v1/contacts/{id}/properties/{property_id} — Set a typed value on an existing contact property

Calls and recordings

• GET /v1/calls — List accessible external calls
• GET /v1/calls/{id} — Get one accessible external call
• GET /v1/calls/{id}/recordings — List recording metadata for a call
• GET /v1/recordings/{id} — Get recording metadata
• GET /v1/recordings/{id}/transcript — Get recording transcript
• GET /v1/recordings/{id}/summary — Get recording summary
• GET /v1/recordings/{id}/download — Get recording download

Conversations, messages, and attachments

• GET /v1/messages — List accessible external conversation messages
• POST /v1/messages — Send one billed external recipient message
• GET /v1/messages/{id} — Get one accessible message
• GET /v1/conversations — List accessible conversations by recent activity
• GET /v1/messages/{id}/attachments — List completed message attachments
• GET /v1/attachments/{id}/download — Get a private message attachment download URL
• POST /v1/message-uploads — Reserve a message media upload
• PUT /v1/message-uploads/{upload_id}/content — Upload exactly the reserved media bytes

Phone numbers and analytics

• GET /v1/phone-numbers — List accessible Waveline phone numbers
• GET /v1/analytics/calls — Read scoped external call analytics

Webhook subscriptions and deliveries

• GET /v1/webhook-subscriptions — List this connection's webhook subscriptions
• POST /v1/webhook-subscriptions — Subscribe to one or more event types
• PATCH /v1/webhook-subscriptions/{id} — Enable or disable a subscription
• DELETE /v1/webhook-subscriptions/{id} — Delete a subscription and cancel outstanding deliveries
• GET /v1/webhook-samples/{event_type} — Get setup samples shaped like live webhook events
• GET /v1/webhook-deliveries — Inspect recent webhook delivery outcomes

Models

All request and response models, including contacts, scoped calls, messages, webhook events, and media.

Authentication

WorkspaceApiKey: wl_live_ or wl_test_ followed by 64 lowercase hex characters. Use separate keys per integration and environment.

OAuthAccessToken: 15-minute OAuth access token obtained using authorization code + S256 PKCE. Discover endpoints at /.well-known/oauth-authorization-server. New connections and rotating refresh tokens have no scheduled expiration. Access tokens still expire after 15 minutes and must be refreshed. Revocation and current connection access remain enforced. Tokens are bound to the resource authorized during consent.

Keep credentials on your server. New API keys created in Waveline have no expiration date. Delete or revoke a connection to stop access. OAuth tokens for an assistant connection are bound to its authorized resource; they are not interchangeable with REST API credentials.

Guides

Access and permissions · Sending messages and billing · Webhooks · Errors and limits