# API Platform API

> REST API for contacts, WhatsApp templates, the inbox, webhooks and reports. Base URL https://mcp.wa-api.cloud/v1. Auth: `Authorization: Bearer $API_KEY`. JSON, snake_case, cursor pagination, problem+json errors.

- [OpenAPI 3.1 spec](https://dev.wa-api.cloud/openapi.json)
- [Full reference as one Markdown file](https://dev.wa-api.cloud/llms-full.txt)

## Guides

- [Make your first request](https://dev.wa-api.cloud/guides/getting-started): Get a key, make a safe test call, then go live.
- [Keys and permissions](https://dev.wa-api.cloud/guides/authentication): Live and test keys, scopes, expiry and the playground.
- [Errors](https://dev.wa-api.cloud/guides/errors): One error format, with a stable code to branch on.
- [Pagination](https://dev.wa-api.cloud/guides/pagination): Cursor paging that stays correct on big workspaces.
- [Safe retries (Idempotency-Key)](https://dev.wa-api.cloud/guides/idempotency): Retry any change without doing it twice.
- [Rate limits and send caps](https://dev.wa-api.cloud/guides/rate-limits): How much you can call, and how the API tells you.
- [Versions](https://dev.wa-api.cloud/guides/versioning): Dated versions, so your integration never breaks by surprise.
- [Dry runs and confirmations](https://dev.wa-api.cloud/guides/dry-runs): Check a change before making it; confirm the ones you cannot undo.
- [Webhooks and signatures](https://dev.wa-api.cloud/guides/webhook-signatures): Receive events, check they came from us, handle retries.
- [Filtering contacts](https://dev.wa-api.cloud/guides/filtering-contacts): Find, count and save contact segments with the same filter the contacts page uses.
- [Recipes](https://dev.wa-api.cloud/recipes): Real-world use cases, step by step.

## Contacts

- [List contacts](https://dev.wa-api.cloud/reference/list-contacts): `GET /v1/contacts`
- [Count contacts](https://dev.wa-api.cloud/reference/count-contacts): `GET /v1/contacts/count`
- [Search contacts](https://dev.wa-api.cloud/reference/search-contacts): `POST /v1/contacts/search`
- [Count contacts by filter](https://dev.wa-api.cloud/reference/count-contacts-by-filter): `POST /v1/contacts/count`
- [Check a contact filter](https://dev.wa-api.cloud/reference/validate-contact-filter): `POST /v1/contacts/filters/validate`
- [Create or update a contact](https://dev.wa-api.cloud/reference/upsert-contact): `POST /v1/contacts`
- [Get a contact](https://dev.wa-api.cloud/reference/get-contact): `GET /v1/contacts/{contact_id}`
- [Update a contact](https://dev.wa-api.cloud/reference/update-contact): `PATCH /v1/contacts/{contact_id}`
- [Delete a contact](https://dev.wa-api.cloud/reference/delete-contact): `DELETE /v1/contacts/{contact_id}`
- [Find a contact by phone](https://dev.wa-api.cloud/reference/lookup-contact): `GET /v1/contacts/lookup`
- [List saved filters](https://dev.wa-api.cloud/reference/list-saved-filters): `GET /v1/saved-filters`
- [Get a saved filter](https://dev.wa-api.cloud/reference/get-saved-filter): `GET /v1/saved-filters/{saved_filter_id}`
- [Save a contact filter](https://dev.wa-api.cloud/reference/create-saved-filter): `POST /v1/saved-filters`
- [Change a saved filter](https://dev.wa-api.cloud/reference/update-saved-filter): `PATCH /v1/saved-filters/{saved_filter_id}`
- [Delete a saved filter](https://dev.wa-api.cloud/reference/delete-saved-filter): `DELETE /v1/saved-filters/{saved_filter_id}`
- [Import contacts in bulk](https://dev.wa-api.cloud/reference/import-contacts): `POST /v1/contacts/import`

## Tags

- [List contact tags](https://dev.wa-api.cloud/reference/list-tags): `GET /v1/tags`
- [Create a tag](https://dev.wa-api.cloud/reference/create-tag): `POST /v1/tags`
- [Add tags to contacts](https://dev.wa-api.cloud/reference/tag-contacts): `POST /v1/contacts/tag`
- [Remove tags from contacts](https://dev.wa-api.cloud/reference/untag-contacts): `POST /v1/contacts/untag`
- [Delete a tag](https://dev.wa-api.cloud/reference/delete-tag): `DELETE /v1/tags/{tag_id}`

## Contact groups

- [List contact groups](https://dev.wa-api.cloud/reference/list-groups): `GET /v1/groups`
- [Create a contact group](https://dev.wa-api.cloud/reference/create-group): `POST /v1/groups`
- [Add contacts to a group](https://dev.wa-api.cloud/reference/add-contacts-to-group): `POST /v1/groups/{group_id}/contacts`
- [Remove contacts from a group](https://dev.wa-api.cloud/reference/remove-contacts-from-group): `DELETE /v1/groups/{group_id}/contacts`
- [Rename a contact group](https://dev.wa-api.cloud/reference/update-group): `PATCH /v1/groups/{group_id}`
- [Delete a contact group](https://dev.wa-api.cloud/reference/delete-group): `DELETE /v1/groups/{group_id}`

## Custom fields

- [List custom fields](https://dev.wa-api.cloud/reference/list-custom-fields): `GET /v1/custom-fields`
- [Create a custom field](https://dev.wa-api.cloud/reference/create-custom-field): `POST /v1/custom-fields`
- [Get a custom field](https://dev.wa-api.cloud/reference/get-custom-field): `GET /v1/custom-fields/{custom_field_id}`
- [Update a custom field](https://dev.wa-api.cloud/reference/update-custom-field): `PATCH /v1/custom-fields/{custom_field_id}`
- [Delete a custom field](https://dev.wa-api.cloud/reference/delete-custom-field): `DELETE /v1/custom-fields/{custom_field_id}`

## Messages

- [Send a WhatsApp template](https://dev.wa-api.cloud/reference/send-template-message): `POST /v1/messages/template`
- [Send a message](https://dev.wa-api.cloud/reference/send-message): `POST /v1/messages`
- [Send a message in a conversation](https://dev.wa-api.cloud/reference/send-conversation-message): `POST /v1/conversations/{conversation_id}/messages`
- [Send a file in a conversation](https://dev.wa-api.cloud/reference/send-conversation-file): `POST /v1/conversations/{conversation_id}/files`
- [Add a system message](https://dev.wa-api.cloud/reference/add-system-message): `POST /v1/conversations/{conversation_id}/system-messages`
- [List messages of a conversation](https://dev.wa-api.cloud/reference/list-conversation-messages): `GET /v1/conversations/{conversation_id}/messages`

## Templates

- [List WhatsApp templates](https://dev.wa-api.cloud/reference/list-templates): `GET /v1/templates`
- [Create a WhatsApp template](https://dev.wa-api.cloud/reference/create-template): `POST /v1/templates`
- [Get a template](https://dev.wa-api.cloud/reference/get-template): `GET /v1/templates/{template_id}`
- [Edit a WhatsApp template](https://dev.wa-api.cloud/reference/update-template): `PUT /v1/templates/{template_id}`
- [Check a template draft](https://dev.wa-api.cloud/reference/lint-template): `POST /v1/templates/lint`
- [Archive templates](https://dev.wa-api.cloud/reference/archive-templates): `POST /v1/templates/archive`
- [Upload a template header sample](https://dev.wa-api.cloud/reference/upload-template-sample): `POST /v1/templates/samples`

## Quick messages

- [List quick messages](https://dev.wa-api.cloud/reference/list-quick-messages): `GET /v1/quick-messages`
- [Create a quick message](https://dev.wa-api.cloud/reference/create-quick-message): `POST /v1/quick-messages`
- [Update a quick message](https://dev.wa-api.cloud/reference/update-quick-message): `PATCH /v1/quick-messages/{quick_message_id}`
- [Delete a quick message](https://dev.wa-api.cloud/reference/delete-quick-message): `DELETE /v1/quick-messages/{quick_message_id}`

## Short links

- [List WhatsApp short links](https://dev.wa-api.cloud/reference/list-short-links): `GET /v1/short-links`
- [Create a short link](https://dev.wa-api.cloud/reference/create-short-link): `POST /v1/short-links`
- [Get a short link](https://dev.wa-api.cloud/reference/get-short-link): `GET /v1/short-links/{short_link_id}`
- [Change a short link's message](https://dev.wa-api.cloud/reference/update-short-link): `PATCH /v1/short-links/{short_link_id}`
- [Delete a short link](https://dev.wa-api.cloud/reference/delete-short-link): `DELETE /v1/short-links/{short_link_id}`

## Broadcasts

- [List broadcasts](https://dev.wa-api.cloud/reference/list-broadcasts): `GET /v1/broadcasts`
- [Get a broadcast](https://dev.wa-api.cloud/reference/get-broadcast): `GET /v1/broadcasts/{broadcast_id}`
- [Check broadcast readiness](https://dev.wa-api.cloud/reference/precheck-broadcast): `POST /v1/broadcasts/precheck`

## Channels

- [List channels](https://dev.wa-api.cloud/reference/list-channels): `GET /v1/channels`

## Conversations

- [List conversations](https://dev.wa-api.cloud/reference/list-conversations): `GET /v1/conversations`
- [Get a conversation and its 24-hour window](https://dev.wa-api.cloud/reference/get-conversation): `GET /v1/conversations/{conversation_id}`
- [Count conversations](https://dev.wa-api.cloud/reference/get-conversation-counts): `GET /v1/conversations/counts`
- [Assign a conversation](https://dev.wa-api.cloud/reference/assign-conversation): `PUT /v1/conversations/{conversation_id}/assignment`
- [Unassign a conversation](https://dev.wa-api.cloud/reference/unassign-conversation): `DELETE /v1/conversations/{conversation_id}/assignment`
- [Close a conversation](https://dev.wa-api.cloud/reference/close-conversation): `POST /v1/conversations/{conversation_id}/close`
- [Reopen a conversation](https://dev.wa-api.cloud/reference/reopen-conversation): `POST /v1/conversations/{conversation_id}/reopen`
- [Add an internal note](https://dev.wa-api.cloud/reference/add-conversation-note): `POST /v1/conversations/{conversation_id}/notes`
- [Tag a conversation](https://dev.wa-api.cloud/reference/tag-conversation): `POST /v1/conversations/{conversation_id}/tags`
- [Untag a conversation](https://dev.wa-api.cloud/reference/untag-conversation): `DELETE /v1/conversations/{conversation_id}/tags`
- [Set a reminder](https://dev.wa-api.cloud/reference/create-conversation-reminder): `POST /v1/conversations/{conversation_id}/reminders`

## Webhooks

- [List endpoints](https://dev.wa-api.cloud/reference/list-webhook-endpoints): `GET /v1/webhooks/endpoints`
- [Create an endpoint](https://dev.wa-api.cloud/reference/create-webhook-endpoint): `POST /v1/webhooks/endpoints`
- [Get an endpoint](https://dev.wa-api.cloud/reference/get-webhook-endpoint): `GET /v1/webhooks/endpoints/{endpoint_id}`
- [Update an endpoint](https://dev.wa-api.cloud/reference/update-webhook-endpoint): `PATCH /v1/webhooks/endpoints/{endpoint_id}`
- [Delete an endpoint](https://dev.wa-api.cloud/reference/delete-webhook-endpoint): `DELETE /v1/webhooks/endpoints/{endpoint_id}`
- [List event types](https://dev.wa-api.cloud/reference/list-webhook-event-types): `GET /v1/webhooks/event-types`
- [Get a sample payload](https://dev.wa-api.cloud/reference/get-webhook-event-sample): `GET /v1/webhooks/event-types/{event_type}/sample`
- [List deliveries](https://dev.wa-api.cloud/reference/list-webhook-deliveries): `GET /v1/webhooks/deliveries`
- [Get a delivery](https://dev.wa-api.cloud/reference/get-webhook-delivery): `GET /v1/webhooks/deliveries/{delivery_id}`
- [List events](https://dev.wa-api.cloud/reference/list-webhook-events): `GET /v1/webhooks/events`
- [Get an event](https://dev.wa-api.cloud/reference/get-webhook-event): `GET /v1/webhooks/events/{event_id}`
- [Turn an endpoint on](https://dev.wa-api.cloud/reference/enable-webhook-endpoint): `POST /v1/webhooks/endpoints/{endpoint_id}/enable`
- [Turn an endpoint off](https://dev.wa-api.cloud/reference/disable-webhook-endpoint): `POST /v1/webhooks/endpoints/{endpoint_id}/disable`
- [Rotate the signing secret](https://dev.wa-api.cloud/reference/rotate-webhook-secret): `POST /v1/webhooks/endpoints/{endpoint_id}/rotate-secret`
- [Set subscriptions](https://dev.wa-api.cloud/reference/set-webhook-subscriptions): `PUT /v1/webhooks/endpoints/{endpoint_id}/subscriptions`
- [Send a test event](https://dev.wa-api.cloud/reference/send-webhook-test): `POST /v1/webhooks/endpoints/{endpoint_id}/test`
- [Retry a delivery now](https://dev.wa-api.cloud/reference/retry-webhook-delivery): `POST /v1/webhooks/deliveries/{delivery_id}/retry`
- [Replay an event](https://dev.wa-api.cloud/reference/replay-webhook-event): `POST /v1/webhooks/events/{event_id}/replay`

## Reports

- [Workspace summary](https://dev.wa-api.cloud/reference/get-workspace-summary-report): `GET /v1/reports/summary`
- [Messaging report](https://dev.wa-api.cloud/reference/get-messaging-report): `GET /v1/reports/messaging`
- [Broadcasts report](https://dev.wa-api.cloud/reference/get-broadcasts-report): `GET /v1/reports/broadcasts`
- [Conversations report](https://dev.wa-api.cloud/reference/get-conversations-report): `GET /v1/reports/conversations`
- [Staff report](https://dev.wa-api.cloud/reference/get-staff-report): `GET /v1/reports/staff`
- [SLA report](https://dev.wa-api.cloud/reference/get-sla-report): `GET /v1/reports/sla`

## Webhook events

- [contact.created/1](https://dev.wa-api.cloud/webhooks/events/contact.created-v1): A new contact was added — in the app, by an import, or through the API.
- [contact.updated/1](https://dev.wa-api.cloud/webhooks/events/contact.updated-v1): A contact changed. `changed_fields` lists which fields (names only).
- [contact.deleted/1](https://dev.wa-api.cloud/webhooks/events/contact.deleted-v1): A contact was deleted.
- [contact.custom_field.updated/1](https://dev.wa-api.cloud/webhooks/events/contact.custom_field.updated-v1): One custom field value of a contact changed.
- [contact.group.added/1](https://dev.wa-api.cloud/webhooks/events/contact.group.added-v1): A contact joined a contact group.
- [contact.group.removed/1](https://dev.wa-api.cloud/webhooks/events/contact.group.removed-v1): A contact left a contact group.
- [contact.import.completed/1](https://dev.wa-api.cloud/webhooks/events/contact.import.completed-v1): A bulk import finished, with its totals.
- [conversation.created/1](https://dev.wa-api.cloud/webhooks/events/conversation.created-v1): A new conversation was opened (usually the first message from a customer).
- [conversation.assigned/1](https://dev.wa-api.cloud/webhooks/events/conversation.assigned-v1): A conversation was assigned to a staff member or a team.
- [conversation.unassigned/1](https://dev.wa-api.cloud/webhooks/events/conversation.unassigned-v1): A conversation went back to the unassigned queue.
- [conversation.closed/1](https://dev.wa-api.cloud/webhooks/events/conversation.closed-v1): A conversation was closed. A new customer message reopens it.
- [conversation.reopened/1](https://dev.wa-api.cloud/webhooks/events/conversation.reopened-v1): A closed conversation was opened again.
- [conversation.note.created/1](https://dev.wa-api.cloud/webhooks/events/conversation.note.created-v1): A staff member (or the API) added an internal note. Notes are never shown to the customer.
- [conversation.mention.created/1](https://dev.wa-api.cloud/webhooks/events/conversation.mention.created-v1): A staff member was @-mentioned in a conversation (in the app, or by a note with mentions through the API). One event per person mentioned. The note text is not included.
- [conversation.tag.added/1](https://dev.wa-api.cloud/webhooks/events/conversation.tag.added-v1): A tag was added to a conversation.
- [conversation.tag.removed/1](https://dev.wa-api.cloud/webhooks/events/conversation.tag.removed-v1): A tag was removed from a conversation.
- [message.created/1](https://dev.wa-api.cloud/webhooks/events/message.created-v1): A customer sent a message. Use it to react to replies such as STOP. Version 1 covers messages from customers only: messages your team, bots or broadcasts send, reactions and system messages do not fire it.
- [broadcast.created/1](https://dev.wa-api.cloud/webhooks/events/broadcast.created-v1): A broadcast was created in the app.
- [tag.created/1](https://dev.wa-api.cloud/webhooks/events/tag.created-v1): A contact or conversation tag was created.
- [sla.warning/1](https://dev.wa-api.cloud/webhooks/events/sla.warning-v1): An SLA clock is close to its due time.
- [sla.breached/2](https://dev.wa-api.cloud/webhooks/events/sla.breached-v2): An SLA clock went past its due time.
- [sla.met/1](https://dev.wa-api.cloud/webhooks/events/sla.met-v1): A reply or close stopped an SLA clock in time.