> ## Documentation Index
> Fetch the complete documentation index at: https://omni.fireflo.au/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/batch

> Send up to 100 identify and track events in one request.

Sends up to 100 events at once — `identify` and `track`, in any mix — each applied as its own endpoint would apply it, in order. One that can't be applied doesn't stop the rest.

Server events need the **OMNI API** and **Customer data** in your plan, and an OMNI API key — not a Customer data source key (`sk_live_…`), which is now refused.

<Note>Needs the `cdp.events:write` scope.</Note>

## Body

| Field | Type | Required | Notes |
| :- | :- | :- | :- |
| `batch` | array | Yes | 1 to 100 events. The whole request is at most 256 KB. |

Each event is the body of [POST /v1/identify](/api-reference/customer-data/identify) or [POST /v1/track](/api-reference/customer-data/track), with a `type`:

| `type` | The event |
| :- | :- |
| `identify` | Who someone is, with `traits` |
| `track` | Something they did, with `event` and `properties`. The default when `type` is left out. |
| `page` | A page they viewed: recorded as `page_viewed`, with `url`, `title`, `referrer` and `path` |

Send an `Idempotency-Key` header to take it once however often the request is retried.

Events are applied in the background, so the answer only says how many were taken. One that can't be applied — no one named, a reserved event name, properties too large — is dropped without stopping the rest, and shows with its reason under **Live events** on **Settings → Data sources** in the panel.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.fireflo.au/v1/batch" \
    -H "Authorization: Bearer $OMNI_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: nightly-sync-2026-10-06" \
    -d '{
      "batch": [
        {
          "type": "identify",
          "user_id": "CUST-10482",
          "phone": "+919876543210",
          "traits": {
            "name": "Asha Rao"
          }
        },
        {
          "type": "track",
          "user_id": "CUST-10482",
          "event": "order_placed",
          "properties": {
            "order_id": "A-1043",
            "total": 2998,
            "currency": "INR"
          },
          "timestamp": "2026-10-06T10:51:03+05:30"
        },
        {
          "type": "track",
          "phone": "+919812345678",
          "event": "cart_added",
          "properties": {
            "sku": "SAREE-RED"
          }
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import os

  import requests

  response = requests.post(
      "https://api.fireflo.au/v1/batch",
      headers={
          "Authorization": f"Bearer {os.environ['OMNI_API_KEY']}",
          "Idempotency-Key": "nightly-sync-2026-10-06",
      },
      json={
          "batch": [
              {
                  "type": "identify",
                  "user_id": "CUST-10482",
                  "phone": "+919876543210",
                  "traits": {
                      "name": "Asha Rao",
                  },
              },
              {
                  "type": "track",
                  "user_id": "CUST-10482",
                  "event": "order_placed",
                  "properties": {
                      "order_id": "A-1043",
                      "total": 2998,
                      "currency": "INR",
                  },
                  "timestamp": "2026-10-06T10:51:03+05:30",
              },
              {
                  "type": "track",
                  "phone": "+919812345678",
                  "event": "cart_added",
                  "properties": {
                      "sku": "SAREE-RED",
                  },
              },
          ],
      },
  )
  print(response.status_code, response.json())
  ```

  ```javascript Node theme={null}
  const response = await fetch("https://api.fireflo.au/v1/batch", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OMNI_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "nightly-sync-2026-10-06",
    },
    body: JSON.stringify({
      "batch": [
        {
          "type": "identify",
          "user_id": "CUST-10482",
          "phone": "+919876543210",
          "traits": {
            "name": "Asha Rao"
          }
        },
        {
          "type": "track",
          "user_id": "CUST-10482",
          "event": "order_placed",
          "properties": {
            "order_id": "A-1043",
            "total": 2998,
            "currency": "INR"
          },
          "timestamp": "2026-10-06T10:51:03+05:30"
        },
        {
          "type": "track",
          "phone": "+919812345678",
          "event": "cart_added",
          "properties": {
            "sku": "SAREE-RED"
          }
        }
      ]
    }),
  });
  console.log(response.status, await response.json());
  ```
</CodeGroup>

## Response

`202 Accepted` — `accepted` is how many events were taken, to be applied in the background.

```json theme={null}
{
  "accepted": 3
}
```

## Errors

Every refusal is `{"error": {"code", "message", "field"}}`; `field` is there when one input is at fault.

| Status | Error code | When |
| :- | :- | :- |
| 400 | `invalid_request` | The body isn't a JSON object, `batch` isn't a list (`field` names it), it is empty, or it has more than 100 events. |
| 413 | `too_large` | The request is over 256 KB. |
| 401 | `key_retired` | The key is a Customer data source key (`sk_live_…`). Those no longer work here: use an OMNI API key with `cdp.events:write` — see [Moving from source keys](/developers/customer-data#moving-from-source-keys). |
| 403 | `scope_missing` | The key doesn't have the `cdp.events:write` scope. |
| 404 | `module_off` | The account doesn't have Customer data on. |

Any request can also be refused for its key, its account or its rate (`key_required`, `invalid_key`, `account_suspended`, `plan_excludes_api`, `address_not_allowed`, `rate_limited`); see [the overview](/api-reference/overview).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.