The IconEngage public API

What the public REST API lets your own systems do, where it lives, how it is versioned and which resources it offers.

The public API lets your own software work with one IconEngage organisation: send every kind of WhatsApp message, upload media, and read or update contacts, conversations, templates and campaigns. Event webhooks do the reverse: they tell your system the moment something happens in IconEngage.

Before you start

Your plan must include the public API. If it does not, creating an API key is refused with a message about your plan. See Plans and trial.
You need an API key. An Owner, Admin or Developer creates one in Settings › API keys. See Create and manage API keys.
Your WhatsApp number must be connected. The API sends through the same numbers as the rest of the app. See Numbers and accounts.

Base URL and versioning

Every endpoint lives under /api/public/v1 on your IconEngage web address. The exact base URL is shown on the API keys page as Public API: …. On iconengage.com it is:

https://iconengage.com/api/public/v1

The v1 in the path is the API's major version. It is versioned separately from the app, so changes to the app's own screens do not change this API. Webhook bodies carry their own version field for the same reason.

Note: An API key only works on /api/public/v1. The app's own /api/v1 addresses refuse it.

How requests work

Authentication: send your key as Authorization: Bearer iek_… on every request. See Authenticate API requests.
Your organisation comes from the key. No request carries an organisation id. A key reaches exactly one organisation.
JSON in, JSON out. Send Content-Type: application/json with a body. The one exception is a file upload to POST /media, which uses multipart/form-data.
Pagination: list endpoints return a page and a next_cursor. Pass it back as ?cursor= to get the next page, and stop when it is null. Set the page size with ?limit= (1 to 100, default 25). Never build a cursor yourself.
Errors always have the same shape: {code, message, request_id, details}. See Rate limits and errors.

What you can do

Each endpoint needs one permission on the key. The permission is named in brackets.

Messages and media

Method and path	What it does
`POST /messages`	Send a message: text, image, video, audio, document, sticker, location, contacts, interactive buttons or lists, reaction, or template (`messages.send`)
`GET /messages/{message_id}`	One message, its status and, if it failed, why (`messages.read`)
`POST /media`	Upload a file, or import one from an https URL, to send by its `media_id` (`messages.send`)
`GET /media/{media_id}`	One media object, with a short-lived download link (`messages.read`)

See Send a message with the API.

Conversations

Method and path	What it does
`GET /conversations`	List conversations, filtered by `contact_id` or `window_state` (`messages.read`)
`GET /conversations/{conversation_id}/messages`	One conversation's messages, filtered by `direction` (`messages.read`)

Contacts

Method and path	What it does
`GET /contacts`	List contacts, searched with `q` or changed since `updated_since` (`contacts.read`)
`POST /contacts`	Create or update a contact by WhatsApp number (`contacts.create`)
`GET /contacts/{contact_id}`	One contact (`contacts.read`)
`PATCH /contacts/{contact_id}`	Update a contact (`contacts.update`)
`POST /contacts/{contact_id}/consent`	Record an opt-in or an opt-out (`contacts.update`)
`POST /contacts/{contact_id}/tags`	Add tags to a contact (`contacts.update`)
`DELETE /contacts/{contact_id}/tags/{tag}`	Remove a tag from a contact (`contacts.update`)
`GET /contact-fields`	Your organisation's custom contact fields (`contacts.read`)
`GET /tags`	Your organisation's tags (`contacts.read`)

Message templates

Method and path	What it does
`GET /templates`	List templates, filtered by `status` or `language` (`templates.read`)
`POST /templates`	Create a template draft (`templates.create`)
`GET /templates/{template_id}`	One template, with its status (`templates.read`)
`POST /templates/{template_id}/submit`	Submit a template to Meta for review (`templates.submit`)

Campaigns

Method and path	What it does
`GET /campaigns`	List campaigns, filtered by `status` (`campaigns.read`)
`POST /campaigns`	Create a campaign (`campaigns.create`)
`GET /campaigns/{campaign_id}`	One campaign (`campaigns.read`)
`GET /campaigns/{campaign_id}/progress`	A campaign's progress (`campaigns.read`)
`POST /campaigns/{campaign_id}/schedule`	Set when a campaign sends (`campaigns.update`)
`POST /campaigns/{campaign_id}/resolve`	Resolve the audience into recipients (`campaigns.send`)
`POST /campaigns/{campaign_id}/launch`	Launch a campaign (`campaigns.send`)
`POST /campaigns/{campaign_id}/pause`	Pause a campaign (`campaigns.send`)
`POST /campaigns/{campaign_id}/resume`	Resume a paused campaign (`campaigns.send`)

Webhook subscriptions

A key can manage its own event webhook subscriptions over the API, as well as on the Event webhooks page.

Method and path	What it does
`GET /webhook-subscriptions`	This key's subscriptions (`developer.webhooks.manage`)
`POST /webhook-subscriptions`	Subscribe this key to events; the answer holds the signing secret, once (`developer.webhooks.manage`)
`PATCH /webhook-subscriptions/{webhook_id}`	Change a subscription (`developer.webhooks.manage`)
`DELETE /webhook-subscriptions/{webhook_id}`	Delete a subscription (`developer.webhooks.manage`)
`POST /webhook-subscriptions/{webhook_id}/test`	Send test events to a subscription (`developer.webhooks.manage`)

A key sees and changes only the subscriptions it owns. See Event webhooks.

Event webhooks and inbound webhooks are different

Event webhooks (this section) send events from IconEngage to your system. Inbound webhooks do the opposite: your system calls IconEngage to start an automation flow.

Still need help?

Write to us at [email protected] and tell us what you were trying to do. Already a customer? Sign in to IconEngage — the same articles are under Help in the app.