The Zynqly API

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

Endpoints

1. /me

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

2. /contacts

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

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

3. /contacts/{id}

   GET — One contact. Scope contacts:read.

   • id (path) — the contact id

4. /conversations

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

   • channel (query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM
   • status (query) — OPEN | SNOOZED | CLOSED
   • cursor (query) — from a previous page's nextCursor
   • limit (query) — 1–100, default 25

5. /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

6. /automations

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

   • channel (query) — INSTAGRAM | WHATSAPP | MESSENGER | TELEGRAM
   • status (query) — ACTIVE | PAUSED | DRAFT | ARCHIVED

7. /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

8. /orders

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

   • status (query) — pending | paid | fulfilled | cancelled | abandoned

9. /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

10. /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 | message.received | comment.received | conversation.assigned | order.created | order.paid | order.abandoned; target_url — the https URL to POST to (a Zapier catch hook, a Make webhook, your server)

11. /hooks/{id}

    DELETE — Unsubscribe. Nothing more is sent to that URL. Scope hooks:write.

    • id (path) — the subscription id

12. /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.
• 404 NOT_FOUNDNo such record in this workspace (the same answer for "not yours").
• 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.