API introduction

The Flowella REST API lets you send WhatsApp messages, manage contacts and opt-outs, list and bulk-send templates, and pull analytics — programmatically. This page covers everything you need to know before calling an endpoint. The full endpoint reference lives in the API reference sidebar (auto-generated from the OpenAPI spec).

Base URL

https://api.flowella.io/v1

All v1 endpoints live under this canonical base — for example https://api.flowella.io/v1/messages.

The API previously lived on the app host at https://app.flowella.io/api/v1/.... Legacy requests to that path are permanently redirected (308) to the canonical https://api.flowella.io/v1/..., preserving the method and body — so existing integrations keep working. Update your base URL when you get a chance to skip the extra hop.

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

Keys are organisation-scoped — they act on a single Flowella org and inherit the permissions of an Admin in that org.

Treat keys like passwords. Never commit them to source control, never paste them in chat or shared docs, and rotate them when teammates leave the org. See Settings → API keys for rotation steps.

Creating a key

You need the Owner or Admin role to manage API keys.

Go to Settings → API keys in the Flowella app.
Click Create key and give it a memorable name.
Copy the key once — it is shown only at creation time.

Treat keys like passwords: never commit them to source control, never paste them in chat, and rotate them when teammates leave the org.

Verifying a key

Hit the ping endpoint to confirm a key is valid:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

A 200 OK with { "ok": true, "organizationId": "…" } means you are authenticated.

Errors

All errors come back in a consistent envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

HTTP status	When you’ll see it
`400`	Validation failed, malformed body, or upstream Meta rejection
`401`	Missing or invalid API key
`402`	Payment required — your subscription does not cover the action
`403`	Forbidden — for example, sending to an opted-out contact, or Meta is not connected
`404`	The requested channel or resource does not exist
`429`	Rate limited — slow down

The error.code field is stable and safe to switch on programmatically. The error.message is human-readable and may change.

Rate limits

API keys are rate-limited per organisation. If you exceed the limit you will get a 429 with code RATE_LIMITED and the message Too many requests. When present, the Retry-After response header tells you how many seconds to wait. Back off and retry with exponential delay. If you are running large bulk sends, prefer POST /v1/templates/send with the throttlePerHour parameter — Flowella enforces the throttle server-side, so you do not need to pace requests yourself.

Idempotency keys

Bulk template sends are asynchronous. POST /v1/templates/send validates the request, queues it durably, and returns 202 Accepted immediately:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

Flowella delivers the batch in the background and retries temporary WhatsApp errors automatically. Recipients are processed individually, so one invalid number does not block the rest of the batch. Follow delivery progress on the template’s Statistics tab in the app. Because delivery happens after the response, retries need to be safe. Pass an Idempotency-Key header (up to 200 characters) that uniquely identifies each batch:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

Repeats of the same key within seven days return the original job id instead of creating a new send. You can safely retry a request after a timeout or network error without messaging anyone twice. If you omit the header, Flowella derives a key from the request body. An identical batch submitted twice in quick succession is therefore not double-sent. An explicit key is still safer, because any change to the body (even reordering recipients) produces a new derived key.

Pagination

List endpoints (/conversations, /contacts, /templates) use cursor pagination:

Pass limit (1–100, default 25) and an optional cursor.
The response contains items and, when there are more results, a nextCursor.
Pass nextCursor back as the cursor parameter to fetch the next page.
When nextCursor is missing, you have reached the end.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

Date and time

All timestamps are ISO 8601 strings in UTC (for example 2025-01-15T14:30:00.000Z). Where the API accepts dates, both date-only (2025-01-15) and full ISO 8601 are coerced server-side.

Phone numbers

Pass phone numbers in E.164 form (+15551234567) where possible. Flowella will normalise common variations server-side, but E.164 is safest.

Channels

Many endpoints accept a whatsappChannelId. If your org has a single channel and you omit it, Flowella uses your default channel. If you have multiple channels, pass the ID explicitly to avoid sending from the wrong sender. For the full URL pattern and channel switching, see Multi-channel.

OpenAPI spec

The machine-readable spec lives at:

/api-reference/openapi.json

Drop it into Postman, Insomnia, or your code generator of choice.

Building an integration? Pair this page with Webhooks to react to events instead of polling for state.

Get Started

Changelog

Essentials

Using the App

Settings

Meta & WhatsApp Setup

HubSpot Integration

Flows & Campaigns

Account & Sign-in

Security & Privacy

API Reference

Troubleshooting

Base URL

Authentication

Creating a key

Verifying a key

Errors

Rate limits

Idempotency keys

Date and time

Phone numbers

Channels

OpenAPI spec

​Base URL

​Authentication

​Creating a key

​Verifying a key

​Errors

​Rate limits

​Idempotency keys

​Pagination

​Date and time

​Phone numbers

​Channels

​OpenAPI spec

Base URL

Authentication

Creating a key

Verifying a key

Errors

Rate limits

Idempotency keys

Pagination

Date and time

Phone numbers

Channels

OpenAPI spec