Skip to content

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 phone
  • conversations:readRead conversations and messages — Inbox threads and their message history
  • messages:writeSend messages — Reply in an open conversation, as your workspace
  • automations:readRead automations — Every automation, its trigger, steps and counts
  • automations:writePause and resume automations — Switch an automation on or off
  • orders:readRead orders — Orders and abandoned carts from every source
  • contacts:writeTag contacts — Add a tag to a contact — what a Zap does when a row is added elsewhere
  • hooks:writeSubscribe to events — Register and remove webhook subscriptions — how Zapier and Make listen for new leads, messages and orders
  • conversations:assignAssign conversations — Give a conversation to a teammate or a team, or put it back in the queue

Endpoints

  • /me

    GET — The workspace this key belongs to, its connected channels and the key's scopes. No scope needed.

  • /contacts

    GET — List contacts (leads) across channels, newest first. Scope contacts:read.

    • channel (query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM | WEBCHAT | SMS | EMAIL
    • status (query) — NEW | CONTACTED | QUALIFIED | CONVERTED | UNSUBSCRIBED
    • search (query) — matches username, name, email or phone
    • page (query) — 1-based page
    • limit (query) — 1–100, default 50
  • /contacts/{id}

    GET — One contact. Scope contacts:read.

    • id (path) — the contact id
  • /conversations

    GET — List inbox conversations, most recent first. Cursor-paged. Scope conversations:read.

    • channel (query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM | WEBCHAT | SMS | EMAIL
    • status (query) — OPEN | SNOOZED | CLOSED
    • cursor (query) — from a previous page's nextCursor
    • limit (query) — 1–100, default 25
  • /conversations/{id}/messages

    GET — A conversation's messages, oldest first within the page. Cursor pages older. Scope conversations:read.

    • id (path) — the conversation id
    • cursor (query) — from a previous page's nextCursor
    • limit (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}/assign

    POST — 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/send

    POST — 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

  • /automations

    GET — List automations across channels. Scope automations:read.

    • channel (query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM | WEBCHAT | SMS | EMAIL
    • status (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

  • /orders

    GET — Orders and abandoned carts from every source, with paid totals. Scope orders:read.

    • status (query) — pending | paid | fulfilled | cancelled | abandoned
  • /contacts/{id}/tags

    POST — 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

  • /hooks

    GET — 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/sample

    GET — 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.

← All help