Batches

Intro

Endpoint: https://api.omnisend.com/v5/batches

Batch operations allow you to perform multiple actions of the same type in a single request, helping you avoid rate limits and improve performance.

Why Use Batches?

Use batches when you need to:

• Create or update multiple resources at once (products, contacts, events, categories)
• Sync large datasets without hitting rate limits
• Perform bulk imports efficiently

Async Processing

Creating a batch is asynchronous. The API immediately returns a batchID and totalCount, then processes items in the background.

Workflow:

1. POST /batches with your items
2. Receive batchID in the response
3. GET /batches/{batchID} to check status
4. GET /batches/{batchID}/items to see individual item results

Batch Status Lifecycle

Supported Endpoints

Note: Each batch can include 1-100 items. The method determines whether items are created (POST) or replaced (PUT).

Example: Create a Batch

curl --request POST \
     --url https://api.omnisend.com/v5/batches \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "method": "POST",
  "endpoint": "contacts",
  "items": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "identifiers": [
        {
          "type": "email",
          "id": "[email protected]",
          "channels": {
            "email": {
              "status": "subscribed"
            }
          }
        }
      ]
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "identifiers": [
        {
          "type": "email",
          "id": "[email protected]",
          "channels": {
            "email": {
              "status": "subscribed"
            }
          }
        }
      ]
    }
  ]
}'

Response:

{
  "batchID": "5f92cbf10cf217478ba93561",
  "totalCount": 2
}

Example: Check Batch Status

curl --request GET \
     --url https://api.omnisend.com/v5/batches/5f92cbf10cf217478ba93561 \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json'

Response shows current status, counts, and timestamps:

{
  "batchID": "5f92cbf10cf217478ba93561",
  "status": "finished",
  "endpoint": "contacts",
  "method": "POST",
  "totalCount": 2,
  "finishedCount": 2,
  "errorsCount": 0,
  "createdAt": "2021-01-01T00:00:00Z",
  "startedAt": "2021-01-01T00:00:01Z",
  "endedAt": "2021-01-01T00:00:05Z"
}

Example: Get Batch Items

To see detailed results for each item (including errors):

curl --request GET \
     --url https://api.omnisend.com/v5/batches/5f92cbf10cf217478ba93561/items \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json'

Each item includes the original request, response, status code, and processing status.

Events Warning

Warning: Before sending a batch of events, ensure there are no active automations in Omnisend that could trigger messages to customers based on the imported data. This could result in duplicate or unwanted messages being sent to customers.

Listing Batches

Use GET /batches with filters to find specific batches:

• endpoint (required): Filter by resource type (products, contacts, events)
• status: Filter by status (pending, inProgress, finished, stopped)
• dateFrom / dateTo: Filter by creation date (format: yyyy-mm-dd)
• limit / offset: Pagination (limit: 1-250, default: 100)

curl --request GET \
     --url 'https://api.omnisend.com/v5/batches?endpoint=contacts&status=finished&limit=50' \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json'