Flowella REST API: auth, scopes, rate limits and errors

The Flowella REST API lets you send WhatsApp messages, manage contacts and opt-outs, work with templates and Flows, and read analytics from your own code. This page covers what you need to know before you call an endpoint. The Endpoints section of this API reference documents individual requests. For the complete, current list, use the live OpenAPI document or the interactive API docs in the app.

Base URL

https://api.flowella.io/v1

Every endpoint lives under this base, for example https://api.flowella.io/v1/messages. Use it even where the app shows an address ending in /api/v1, such as API base URL in the Developer hub.

Requests to the app host, https://app.flowella.io/api/v1/..., are permanently redirected (308) to https://api.flowella.io/v1/.... Many HTTP clients drop the Authorization header when they follow a redirect to another host, so the redirected request can fail with 401. Call https://api.flowella.io/v1 directly.

Authentication

Send a bearer token in the Authorization header of every request:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Flowella accepts two kinds of token. Both act on one organisation only.

Token	Starts with	Where it comes from	Scopes	Expiry
API key	`flo_`	Settings → API keys, created by an Owner or Admin. See API keys.	Every scope	None. Works until revoked.
OAuth access token	`fla_`	An OAuth app registered under Settings → Developer apps. See Register a partner app with OAuth.	Only the scopes granted when the app was authorised	1 hour. Request a new token when it expires.

Use an API key for your own scripts and integrations. Use an OAuth app when other Flowella organisations install your integration.

Treat keys and tokens like passwords. Never commit them to source control or paste them into chat or shared documents. Revoke a key you no longer need in API keys.

Check your credentials

Call the ping endpoint to confirm that a key or token works:

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

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

import os
import requests

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

A 200 OK response means you are authenticated. organizationId is your organisation’s numeric ID:

{
  "ok": true,
  "organizationId": 4821
}

A 401 response has the code UNAUTHORIZED and one of these messages: Missing bearer token, Invalid or expired API key, Invalid or expired access token or Unsupported bearer token.

Scopes

Each endpoint needs a scope. API keys created in the app have every scope. OAuth access tokens have only the scopes granted at authorisation.

Scope	Allows
`messages:read`	Reading messages.
`messages:write`	Sending messages with `POST /v1/messages`.
`contacts:read`	Reading contacts and opt-outs.
`contacts:write`	Creating, updating and deleting contacts, bulk upserts and recording opt-outs.
`conversations:read`	Reading conversations and WhatsApp channels.
`conversations:write`	Updating, closing and reopening conversations.
`templates:read`	Reading templates and their approval status.
`templates:write`	Creating, editing, submitting and deleting templates, test sends and bulk sends with `POST /v1/templates/send`.
`webhooks:manage`	Managing webhooks, deliveries, replays and signing secrets.
`analytics:read`	Reading analytics and usage.
`account:read`	Reading capabilities, integration status and request details.
`flows:read`	Reading Flows and their sync status.
`flows:write`	Creating, editing, publishing and deleting Flows, and setting up form providers.
`forms:ingest`	Sending and reading form submissions, including inbound form webhooks.
`events:read`	Reading the event feed with `GET /v1/events`.
`jobs:read`	Reading background jobs and their results.
`jobs:write`	Cancelling background jobs.
`sandbox:manage`	Reading and changing the sandbox setting, and using the sandbox test tools.

GET /v1/ping and GET /v1/rate-limits need no scope. GET /v1/capabilities (scope account:read) lists the scopes your token has. A request without the scope it needs returns 403 with the code INSUFFICIENT_SCOPE. details.required lists the missing scopes:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token is missing required scope(s)",
    "requestId": "req_5b1e0c2a-8f3d-4e6a-9c7b-2d4f6a8e0b1c",
    "details": { "required": ["webhooks:manage"] }
  }
}

Errors

Errors use the same envelope. requestId identifies the request when you contact support, and details holds extra information, such as validation issues, when there is any:

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

HTTP status	`error.code`	When you see it
`400`	`BAD_REQUEST`	The request failed validation, the `API-Version` is not supported, or the `Idempotency-Key` has the wrong length.
`400`	`META_ERROR`	Meta rejected the request.
`400`	`INVALID_TEMPLATE_NAME`, `INVALID_TEMPLATE_COMPONENTS`	The template name or components are not valid.
`401`	`UNAUTHORIZED`	The bearer token is missing, invalid, revoked or expired.
`402`	`PAYMENT_REQUIRED`	Your subscription payment is past due.
`403`	`INSUFFICIENT_SCOPE`	Your token does not have a scope the endpoint needs.
`403`	`FORBIDDEN`	The action is not allowed, for example sending to a contact who opted out on that number, or your subscription is not active.
`404`	`NOT_FOUND`	The resource does not exist in your organisation.
`409`	`CONFLICT`, `IDEMPOTENCY_KEY_CONFLICT`, `IDEMPOTENCY_KEY_IN_FLIGHT`	A duplicate value such as an `externalId`, or an idempotency key clash.
`429`	`RATE_LIMITED`	You sent too many requests. See Rate limits.
`500`	`INTERNAL_ERROR`, `INTERNAL_SERVER_ERROR`	Something went wrong on Flowella’s side. Retry later and quote the `requestId` to support.

The error.code value is stable, so your code can rely on it. The error.message text is for people and may change.

Rate limits

Each API key and each OAuth access token has its own limit on requests per minute. Flowella counts requests in fixed one-minute windows that start on the minute (UTC). Responses to requests that pass the authentication and scope checks include these headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in each window.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	When the current window ends, in Unix seconds.

When you go over the limit, Flowella returns 429 with the code RATE_LIMITED and a Retry-After header with the number of seconds to wait. GET /v1/rate-limits returns your limit, remaining and reset values as JSON. For large sends, use POST /v1/templates/send, which takes up to 50,000 recipients in one request. The request also accepts an optional throttlePerHour field, a whole number from 1 to 100,000, but it doesn’t pace sends at the moment, so don’t rely on it. To spread a large send over time, split the recipient list into smaller batches and send each batch separately.

Request IDs

Responses include an X-Request-Id header, and error bodies repeat it as error.requestId. POST /v1/templates/send is the exception: see Bulk template sends. To use your own ID, send an X-Request-Id header of up to 128 characters and Flowella reuses it. Quote the request ID when you contact support. To look up a request yourself, call GET /v1/requests/{requestId} (scope account:read): it returns the logged request with the events, jobs and webhook deliveries linked to it. The Developer hub lists your recent requests and their IDs.

Idempotency

Idempotency keys let you retry a write request after a timeout or network error without doing the work twice. POST /v1/templates/send follows its own rules, described below.

Most write requests

POST, PATCH, PUT and DELETE requests accept an optional Idempotency-Key header:

The key must be 8 to 255 characters. Other lengths return 400.
Flowella remembers each key for your organisation for 24 hours.
A repeat with the same key, method, path and body returns the stored response without running the request again.
A repeat with the same key but a different method, path or body returns 409 IDEMPOTENCY_KEY_CONFLICT.
A repeat sent while the first request is still running returns 409 IDEMPOTENCY_KEY_IN_FLIGHT. Wait and retry.
Responses echo the key in an Idempotency-Key header.

Requests without the header run normally, with no protection against duplicates.

Bulk template sends

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

{
  "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. Pass an Idempotency-Key header that identifies each batch:

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

This endpoint handles keys differently from other write requests:

The key can be up to 200 characters. A longer key returns 400.
A repeat with the same key within 7 days returns the original id and sends nothing, even if the body changed.
Without the header, Flowella uses a hash of the request body as the key. If you send a byte-identical body again within 7 days, you get the original id back and nothing is sent. Use a new key for every batch you mean to send.

Some other behaviour also differs for this endpoint:

Call it with an API key. OAuth access tokens are refused with 401.
Its responses do not include the X-Request-Id, API-Version or X-RateLimit-* headers. Its requests still count towards the key’s rate limit.

Versioning

You can pin the API version with the API-Version header:

API-Version: 2026-08-11

2026-08-11 is the only supported version and the default when you leave the header out. Any other value, or a value that is not a YYYY-MM-DD date, returns 400 with the message Unsupported API-Version. Responses echo the version in the API-Version and X-Flowella-Api-Version headers.

Sandbox

The sandbox lets you test an integration without sending anything to WhatsApp. It works on your real organisation: there is no separate test account. You can use it in two ways:

A sandbox key, which affects only requests made with that key. See Sandbox keys.
The organisation-wide API sandbox in the Developer hub, which an Owner or Admin can turn on. See API sandbox.

While the sandbox applies, POST /v1/messages stores the message and returns "sandbox": true without contacting Meta, and template submission returns an instant mock decision. The sandbox test tools under /v1/test/ and /v1/sandbox need the sandbox:manage scope.

Pagination

List endpoints, such as /v1/conversations, /v1/contacts and /v1/templates, use cursor pagination:

Pass limit (1 to 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 or null, you have reached the end.

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

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 values work.

Phone numbers

Pass phone numbers in E.164 form (+15551234567) where possible. Flowella normalises common variations, but E.164 is safest.

Channels

Many endpoints accept a whatsappChannelId. If your organisation has a single channel and you omit it, Flowella uses your default channel. If you have several channels, pass the ID explicitly so you do not send from the wrong number. For the full URL pattern and channel switching, see Multi-channel.

OpenAPI spec

The live, machine-readable specification is public:

https://api.flowella.io/v1/openapi.json

Import it into Postman, Insomnia or a code generator. It describes both API key and OAuth authentication.

Developer resources

The app has more developer material. These pages are public, so you can open them without signing in:

Resource	Address
Interactive API docs, with try-it requests	`https://app.flowella.io/docs`
Postman collection (downloads a `.json` file)	`https://app.flowella.io/docs/postman`
Sandbox guide	`https://app.flowella.io/docs/sandbox`
Quickstarts in Markdown for Salesforce, Zoho CRM, SurveyMonkey, Typeform and n8n	`https://app.flowella.io/docs/quickstarts/salesforce`, with `zoho`, `surveymonkey`, `typeform` or `n8n` in place of `salesforce`

The Developer hub in Settings brings these links together with your recent API requests and the API sandbox switch.

Pair this page with the webhooks reference to react to events instead of polling for changes.

Get Started

Essentials

Using the App

Settings

Meta & WhatsApp Setup

HubSpot Integration

Flows & Campaigns

API Reference

Troubleshooting

Changelog

Flowella REST API: auth, scopes, rate limits and errors

Base URL

Authentication

Check your credentials

Scopes

Errors

Rate limits

Request IDs

Idempotency

Most write requests

Bulk template sends

Versioning

Sandbox

Date and time

Phone numbers

Channels

OpenAPI spec

Developer resources

​Base URL

​Authentication

​Check your credentials

​Scopes

​Errors

​Rate limits

​Request IDs

​Idempotency

​Most write requests

​Bulk template sends

​Versioning

​Sandbox

​Pagination

​Date and time

​Phone numbers

​Channels

​OpenAPI spec

​Developer resources

Base URL

Authentication

Check your credentials

Scopes

Errors

Rate limits

Request IDs

Idempotency

Most write requests

Bulk template sends

Versioning

Sandbox

Pagination

Date and time

Phone numbers

Channels

OpenAPI spec

Developer resources