API Reference

The OmniFlow API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Authentication

Authenticate your API requests using your account's Secret Key. You can manage your API keys in the Console.

Authentication to the API is performed via HTTP Basic Auth or Bearer tokens. Provide your API key as the basic auth username value (you do not need to provide a password).

Keep your keys safe

Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas.

Base URL

https://api.omniflow.com/v1/

Authentication Example

curl https://api.omniflow.com/v1/messages \
  -u sk_live_v2_9f8e7d6c5b4a3...:

Create a message

Dispatches a new message. OmniFlow will automatically handle routing based on the selected channel (WhatsApp, SMS, Email).

POST /v1/messages

Body Parameters

to required

The destination phone number (in E.164 format) or email address.

from optional

The sender ID or phone number. If omitted, OmniFlow will use your default sender pool.

channel required

The routing channel. Must be one of: WHATSAPP, SMS, EMAIL.

content required

A dictionary containing the payload. For templates, pass template_id and variables.

status_callback optional

A URL that OmniFlow will send webhooks to every time the message status changes (e.g., delivered, failed).

Request

cURL

curl https://api.omniflow.com/v1/messages \
  -u sk_live_v2_9f8e7d6c5: \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "WHATSAPP",
    "to": "+919876543210",
    "from": "omni_verify",
    "content": {
      "template_id": "auth_otp",
      "variables": { "code": "849201" }
    },
    "status_callback": "https://your-app.com/webhooks/omniflow"
  }'

Response 202 Accepted

{
  "id": "msg_019ec8f3a1b2",
  "object": "message",
  "channel": "whatsapp",
  "to": "+919876543210",
  "status": "queued",
  "created_at": 1718329481
}

Retrieve a message

Retrieves the details of an existing message. You need only supply the unique message identifier that was returned upon message creation.

GET /v1/messages/:id

Path Parameters

id required

The identifier of the message to be retrieved.

Request

curl https://api.omniflow.com/v1/messages/msg_019ec8f3a1b2 \
  -u sk_live_v2_9f8e7d6c5:

Response 200 OK

{
  "id": "msg_019ec8f3a1b2",
  "object": "message",
  "channel": "whatsapp",
  "to": "+919876543210",
  "status": "delivered",
  "delivered_at": 1718329484,
  "provider_latency_ms": 1420
}

List all messages

Returns a list of your messages. The messages are returned sorted by creation date, with the most recent messages appearing first. Uses cursor-based pagination to handle massive data sets.

GET /v1/messages

Query Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

cursor optional

A cursor for use in pagination. next_cursor or prev_cursor.

Request

curl -G https://api.omniflow.com/v1/messages \
  -u sk_live_v2_9f8e7d6c5: \
  -d limit=2

Response 200 OK

{
  "data": [
    {
      "id": "msg_019ec8f3a1b2",
      "object": "message",
      "status": "delivered"
    },
    {
      "id": "msg_019ec8f3a1b1",
      "object": "message",
      "status": "failed"
    }
  ],
  "next_cursor": "eyJpZCI6Im1zZ18wMTllYzh...",
  "prev_cursor": null,
  "has_more": true
}