Zyflow REST API

# Base URL and authentication

Every call goes to https://app.zyflowcrm.com/api/v1, sends and receives JSON, and carries an API key in the Authorization header as a Bearer token. A key belongs to one workspace. The REST API takes API keys only; OAuth sign-in is for AI apps on the MCP server.

If one login runs several businesses (up to 10 workspaces per login), create a key in each workspace.

curl "https://app.zyflowcrm.com/api/v1/contacts?limit=5" \
  -H "Authorization: Bearer $ZYFLOW_API_KEY"

Without a valid key, you get 401:

{"error":true,"code":"unauthenticated","message":"Sign in, or send your API key as \"Authorization: Bearer zf_live_...\".","status":401}

The same key also works as a Bearer token on the MCP server, for AI apps that can’t sign in. See Connect any MCP app.

# Create and manage API keys

Create Zyflow API keys on the Connect page. Choose New key, name it after where it’s used, like “Website form”, and pick Read and write or Read only. The key starts with zf_live_ and is shown once. Changes made with it appear in History under that name, and you can revoke it instantly.

Names can be up to 60 characters. Copy the key when it appears: Zyflow keeps only a hash, so it can’t be shown again. The panel lists each key by name, first characters and last use, and revoking is instant: “Anything using this key stops working immediately.”

Active keys: Free 3, Solo 10, Team 50, Pro 200. At the limit, a new key answers 402 api_key_limit. Revoke one you no longer use.

Before you hand out a key

# Keep your key on a server

Don’t call the Zyflow API from browser code. Cross-origin requests are accepted only from Zyflow’s own sites, and any key, even a read-only one, can export your records, documents and history. Keep the key in a server or serverless function, and have your page post to that.

# The OpenAPI reference

The full reference is generated from the code: Swagger UI at https://app.zyflowcrm.com/api/docs and the OpenAPI document at https://app.zyflowcrm.com/api/docs/json (“Zyflow API” v1.0.0). This page covers keys, conventions and examples. The reference lists every /api/v1 route, field and response.

Only /api/v1 paths accept keys. Routes are grouped by contacts, companies, deals, memories, activities, tasks, files, documents, business, insights, history, settings and data.

Don’t mix up the two addresses: this guide is /docs/api on the Zyflow site, and the generated reference is /api/docs on the app.

Read the OpenAPI reference

# Conventions

Every route follows the same rules: typed ids, one change per write request, version checks, cursor paging, and saves that find the record you already have.

# Errors

Every error has the same JSON shape: error, code, message, status and, sometimes, details. Branch your code on code, and show message to a person: each one says what went wrong and what to do next.

{"error":true,"code":"insufficient_scope","message":"This connection is read-only. Reconnect with write access, or use an API key that has crm:write.","status":403}

Cost and rate limits

REST API calls are never billed, and there are no AI or API credits.² Short burst limits per key stop runaway scripts. Over the limit, you get 429 with a Retry-After header.

# History and undo

Every write returns a batchId. To reverse it, POST to /api/v1/changes/{batchId}/undo. Everything that request changed goes back in one step, fields edited again since are kept, and the undo is itself a change you can undo.¹

curl -X POST "https://app.zyflowcrm.com/api/v1/changes/bat_…/undo" \
  -H "Authorization: Bearer $ZYFLOW_API_KEY"

Response:

{"batchId":"bat_…","undone":[…],"skipped":[]}

The answer lists undone and skipped items (each skip with a reason) and its own batchId. You get 404 for a batch that isn’t in this workspace, 409 already_undone, or 402 history_limit when the change is older than your plan’s history window.

Find changes

GET /api/v1/changes returns batches (each with undoable and undoneAt) and hasMore. Filter by entityId, entityType, via (app, mcp, api, import or system), clientName (a key’s name) and since (an ISO date and time). It pages with limit, up to 100, and offset, not a cursor.

In the app, your code’s changes show in History under the API tab with the key’s name, and in “What your AI did” as “via API”.

Undo can’t reverse settings changes, creating or revoking keys, files deleted for good or an emptied trash, or deleting a workspace.

# Documents: invoices, quotes and letters

POST /api/v1/documents makes an invoice, quote or letter from a template. Zyflow numbers it when it’s issued, works out totals and tax, renders the PDF and files it. To record a payment, post an amount to /documents/{id}/status. Zyflow doesn’t send documents to customers or collect payments.

Issued invoices and quotes are voided, not deleted. With documents switched off, these routes answer 404 documents_off.

Zyflow works out totals, tax and numbering. Unit prices come from what you or your AI enter; there’s no price list. Zyflow records payments; it doesn’t collect them, and there are no card payment links. Zyflow sends nothing to your customers.

# Export your data from code

GET /api/v1/export/{type} returns contacts, companies, deals, tasks, activities or memories as CSV, or workspace.json with your settings, records, documents, change history (up to 100,000 changes) and links to every file. File contents download separately. Any key can export, including a read-only one.³

Types: contacts.csv, companies.csv, deals.csv, tasks.csv, activities.csv, memories.csv and workspace.json. Zyflow runs no scheduled backups, so schedule your own with a Read only key named “Nightly export”.

curl "https://app.zyflowcrm.com/api/v1/export/workspace.json" \
  -H "Authorization: Bearer $ZYFLOW_API_KEY" \
  -o "zyflow-$(date +%F).json"

Export your data

# What the REST API doesn’t do

Zyflow has no webhooks, event subscriptions or official SDKs. To pick up changes, poll GET /api/v1/changes with since, or list records with updatedAfter. REST has no idempotency keys, so save contacts with ?upsert=true to land on the record you already have.

A poll every few minutes (store the time of your last check):

curl "https://app.zyflowcrm.com/api/v1/changes?since=2026-10-03T07:00:00Z&limit=100" \
  -H "Authorization: Bearer $ZYFLOW_API_KEY"

There are no native Zapier, Make or n8n apps. A tool with a generic HTTP step can call the API from its own servers, with the key stored in that tool’s credentials.

How the REST API differs from the MCP server

Both reach the same records. AI apps use the MCP server: they sign in with OAuth and call tools shaped around tasks. Your code uses the REST API with an API key and routes shaped around records. A few behaviors differ:

• What’s missing
• Zyflow limits

# Examples

Create or update a contact

Run this once for 201 and created. Run it again for 200 and updated or unchanged, on the same contact.

curl -X POST "https://app.zyflowcrm.com/api/v1/contacts?upsert=true" \
  -H "Authorization: Bearer $ZYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maya Chen","company":"Northwind","emails":["maya@northwind.example"],"source":"Website form","tags":["website"]}'

Response (trimmed):

{
  "action": "created",
  "record": { "id": "ct_…", "type": "contact", "fullName": "Maya Chen", "version": 1, "clientName": "Website form", … },
  "related": { "company": { "action": "created", "id": "co_…", "name": "Northwind" } },
  "warnings": [],
  "batchId": "bat_…"
}

A website form through a small server-side relay

Your page posts the form to a small function on your server that holds the key and makes three calls: save the contact, log the message, set a follow-up. It needs Node 18 or newer and reads ZYFLOW_URL (your Zyflow address) and ZYFLOW_API_KEY from the environment. Wire handleFormPost to your host’s request handler.

// Runs on your server, never in the browser. Node 18 or newer.

const BASE = `${process.env.ZYFLOW_URL}/api/v1`;
const KEY = process.env.ZYFLOW_API_KEY; // a "Website form" key, Read and write

async function zyflow(path, body) {
  const res = await fetch(BASE + path, {
method: "POST",
headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
body: JSON.stringify(body),
  });
  const data = await res.json();
  if (res.ok === false) throw new Error(`${data.code}: ${data.message}`);
  return data;
}

export async function handleFormPost(form) {
  if (form.website) return { ok: true }; // honeypot: people leave this hidden field empty
  const name = String(form.name ?? "").trim().slice(0, 160);
  const email = String(form.email ?? "").trim().slice(0, 254);
  const message = String(form.message ?? "").trim().slice(0, 5000);
  if (name === "" || message === "" || email.includes("@") === false) {
    return { ok: false, error: "Please fill in your name, email and message." };
  }

  // 1. Land on the contact you already have, matched by email
  const saved = await zyflow("/contacts?upsert=true", {
name, emails: [email], source: "Website form", tags: ["website"],
  });

  // 2. More than one contact could match: stop, and keep the candidates for a person
  if (saved.action === "ambiguous") return { ok: true, review: saved.candidates };
  const contactId = saved.record.id;

  // 3. Log the message on that contact
  await zyflow("/activities", { contactId, kind: "message", title: "Website form", body: message });

  // 4. Optional: a follow-up for tomorrow, in the workspace's time zone
  await zyflow("/tasks", { contactId, title: `Reply to ${name}'s website message`, due: "tomorrow" });

  return { ok: true };
}

Spot an error? Tell us