For developers

API

Let your web shop, Zapier, Make or your own code talk to EveryConvo. Someone buys your course: send the welcome flow and add a tag, without opening the dashboard.

Getting started

Create a key in Settings, under API keys. You see it once; keep it like a password. Send it with every request:

curl https://app.everyconvo.com/api/orgs/YOUR_WORKSPACE_ID/flows \
  -H "Authorization: Bearer ec_..."

The workspace ID is in the dashboard's address bar, after /orgs/.

What a key can and cannot do

It acts on behalf of the person who created it, and can never do more than an editor: no team members, no subscription, nothing about the workspace itself.
It only works for the workspace it was created in.
If its creator leaves the workspace, or you revoke it, it stops working immediately.
At most 120 requests per minute per key. Above that you get 429; wait a minute.

Contacts

GET /orgs/{workspace}/contacts

A page of contacts, newest first. Filters, all optional:

Parameter	Meaning
`username`	Instagram username, exact, with or without `@`. The way to find someone you only know by name
`q`	Searches name and email address
`tag`	ID of a tag
`limit`, `cursor`	At most 200 per page. Pass `nextCursor` from the response to get the next one

curl "https://app.everyconvo.com/api/orgs/$ORG/contacts?username=noor.bakes" \
  -H "Authorization: Bearer $KEY"

{ "contacts": [ { "id": "0192…", "name": "Noor", … } ], "nextCursor": null }

GET /orgs/{workspace}/contacts/{contact}

One contact, with tags and fields.

PUT /orgs/{workspace}/contacts/{contact}/fields

Fills custom fields by key. null clears a field. If one field is wrong, nothing changes and you are told which one.

curl -X PUT "https://app.everyconvo.com/api/orgs/$ORG/contacts/$CONTACT/fields" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "values": { "plan": "course", "spent": 149, "customer_since": "2026-09-17" } }'

POST /orgs/{workspace}/contacts/bulk-tag

Adds a tag to, or removes it from, up to 1,000 contacts at once.

{ "contactIds": ["0192…"], "tagId": "0193…", "action": "add" }

GET /orgs/{workspace}/tags · GET /orgs/{workspace}/fields

The tags and fields that exist, with their ID and key.

Flows

GET /orgs/{workspace}/flows

All flows, with their ID and whether they are published.

POST /orgs/{workspace}/flows/{flow}/start

Starts a published flow for one contact, in their conversation.

curl -X POST "https://app.everyconvo.com/api/orgs/$ORG/flows/$FLOW/start" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "contactId": "0192…" }'

{ "runId": "0194…", "started": true }

If the contact is already in this flow, nothing new starts and you get "started": false back. That way a Zap that fires twice does not send two welcome messages. To start over anyway, pass "restart": true.

Worth knowing: Instagram only lets you message someone within 24 hours of them messaging you. If you start a flow for someone who has been quiet for longer, the flow runs but the messages do not arrive. Tags and fields in that flow are still set.

Receiving events

The other direction, EveryConvo telling your system something, works through webhooks, in Settings under Webhooks. Every request carries the header x-everyconvo-signature with t= (timestamp) and v1=, an HMAC-SHA256 over {t}.{body} using your signing secret.

Errors

Code	Meaning
`400`	The request is invalid. `message` says why
`401`	No key, a wrong key or a revoked key
`403`	A key is not allowed to do this
`404`	Does not exist, or does not belong to this workspace
`409`	Not possible right now: flow not published, contact opted out
`429`	Too many requests; wait a minute

{ "error": "contact_opted_out", "message": "this contact has opted out" }