Help · API
The Zynqly API
Read your contacts, conversations, automations and orders, send messages and pause automations from your own systems — across all seven channels: Instagram, WhatsApp, Messenger, Telegram, website chat, SMS and email. Version 1.0.0. Base path /api/v1; the machine-readable document is at /api/v1/openapi.json.
Authentication
Create a key in Settings → API keys (API access must be part of your plan) and send it on every request:
curl https://zynqly.com/api/v1/me \ -H "Authorization: Bearer zk_live_…"
A key acts as the workspace it was created in and can only do what it was given. 120 requests per minute per key. Answers are JSON: { data, meta } on success, { error: { code, message } } otherwise.
Scopes
contacts:readRead contacts — Leads on every channel, with tags, email and phoneconversations:readRead conversations and messages — Inbox threads and their message historymessages:writeSend messages — Reply in an open conversation, as your workspaceautomations:readRead automations — Every automation, its trigger, steps and countsautomations:writePause and resume automations — Switch an automation on or offorders:readRead orders — Orders and abandoned carts from every sourcecontacts:writeTag contacts — Add a tag to a contact — what a Zap does when a row is added elsewherehooks:writeSubscribe to events — Register and remove webhook subscriptions — how Zapier and Make listen for new leads, messages and ordersconversations:assignAssign conversations — Give a conversation to a teammate or a team, or put it back in the queue
Endpoints
/meGET — The workspace this key belongs to, its connected channels and the key's scopes. No scope needed.
/contactsGET — List contacts (leads) across channels, newest first. Scope
contacts:read.channel(query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM | WEBCHAT | SMS | EMAILstatus(query) — NEW | CONTACTED | QUALIFIED | CONVERTED | UNSUBSCRIBEDsearch(query) — matches username, name, email or phonepage(query) — 1-based pagelimit(query) — 1–100, default 50
/contacts/{id}GET — One contact. Scope
contacts:read.id(path) — the contact id
/conversationsGET — List inbox conversations, most recent first. Cursor-paged. Scope
conversations:read.channel(query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM | WEBCHAT | SMS | EMAILstatus(query) — OPEN | SNOOZED | CLOSEDcursor(query) — from a previous page's nextCursorlimit(query) — 1–100, default 25
/conversations/{id}/messagesGET — A conversation's messages, oldest first within the page. Cursor pages older. Scope
conversations:read.id(path) — the conversation idcursor(query) — from a previous page's nextCursorlimit(query) — 1–100, default 30
POST — Send a text reply in a conversation, as your workspace. Channel messaging-window rules apply. Scope
messages:write.id(path) — the conversation id
Body:
text— string, up to 4000 characters/conversations/{id}/assignPOST — Give a conversation to a teammate or a team, or put it back in the queue. Send the assignVersion you last read as expectedVersion: if someone changed the owner since, the answer is 409 ASSIGN_CONFLICT and nothing changes. Scope
conversations:assign.id(path) — the conversation id
Body:
userId— optional — the teammate who takes it (a member who can reply);teamId— optional — the team it goes to;unassign— optional — true puts it back in the unassigned queue;expectedVersion— optional integer — the assignVersion you last read/whatsapp/templates/sendPOST — Send an approved WhatsApp template to a phone number — works outside the 24-hour window. Variables, header media, link endings and offer codes are filled for you where the template saved a source. Scope
messages:write.Body:
to— phone number with country code;template— the template name;language— optional, e.g. en_US;accountId— needed when the workspace has more than one WhatsApp number;variables— object — { first_name: "Priya" } for named blanks; or params: ["Priya"] for numbered;header— optional { link } for a media header, or { location: { latitude, longitude, name, address } };linkEndings— optional array — the end of each website button link that takes one;couponCode— optional, for offer and coupon templates;offerEndsAt— optional ISO time a limited-time offer ends;code— the one-time code, for login-code templates/automationsGET — List automations across channels. Scope
automations:read.channel(query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM | WEBCHAT | SMS | EMAILstatus(query) — ACTIVE | PAUSED | DRAFT | ARCHIVED
/automations/{id}GET — One automation with its trigger, steps and attributed revenue. Scope
automations:read.id(path) — the automation id
PATCH — Pause or resume an automation. Scope
automations:write.id(path) — the automation id
Body:
status— ACTIVE | PAUSED/ordersGET — Orders and abandoned carts from every source, with paid totals. Scope
orders:read.status(query) — pending | paid | fulfilled | cancelled | abandoned
/contacts/{id}/tagsPOST — Add a tag to a contact. Idempotent — tagging twice is one tag. Scope
contacts:write.id(path) — the contact id
Body:
tag— string, up to 40 characters/hooksGET — List this workspace's webhook subscriptions. Scope
hooks:write.POST — Subscribe an https URL to an event. The signing secret is returned once, on this response. Scope
hooks:write.Body:
event— one of lead.created | tag.added | form.submitted | message.received | comment.received | conversation.assigned | order.created | order.paid | order.abandoned | contacts.import.completed;target_url— the https URL to POST to (a Zapier catch hook, a Make webhook, your server)/hooks/{id}DELETE — Unsubscribe. Nothing more is sent to that URL. Scope
hooks:write.id(path) — the subscription id
/hooks/sampleGET — A sample delivery for an event, as a one-item list — what Zapier shows while a Zap is being built. Scope
hooks:write.event(query) — the event id, e.g. lead.created
Errors
401 UNAUTHENTICATEDNo Authorization: Bearer header.401 INVALID_KEYThe key is unknown or has been revoked.402 PLAN_LIMIT_REACHEDThe workspace's plan does not include API access.403 INSUFFICIENT_SCOPEThe key was not given the scope this endpoint needs.403 INSUFFICIENT_ACCESSThe person who made the key no longer has the access this endpoint needs in this workspace.404 NOT_FOUNDNo such record in this workspace (the same answer for "not yours").409 ASSIGN_CONFLICTSomeone else changed the conversation's owner since the expectedVersion you sent. Read it again.422 ASSIGNEE_NOT_ELIGIBLEThat person can't take conversations in this workspace (not a member, or a Viewer).422 VALIDATION_ERRORA parameter or body field is missing or malformed.429 RATE_LIMITEDMore than 120 requests in a minute on one key. Retry after the Retry-After seconds.