Customer.io
v1.0.0
OpenAPI 3.1.0

Batch requests

US region

Client Libraries
Shell Curl

Batch requests

​

The batch method helps you send an array of identify, group, track, page, screen, and/or alias requests in a single call, so you don't have to send multiple requests. Our server-side sources use this method automatically to increase performance.

Requests are limited to 500KB total per request and 32KB per call in the request. A top-level context object is the default for every call in the batch: we apply it to each call that doesn't include its own context. Set integrations on individual calls; a top-level integrations object has no effect.

Headers
  • X-Strict-Mode
    enum
    const:  
    1

    Set to 1 to turn on strict mode, which validates each request and returns an error when it fails. Without this header, the API returns a 200 response for almost every request and logs errors in Customer.io. Learn more

    values
    • 1
Body
application/json
  • batch
    Type: array

    A group of requests you want to send to Pipelines in the call. Each request must include a type so we know which endpoint to route it to.

  • context

    The default context for every call in the batch. We apply it to each call that doesn't include its own context object.

    A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

    • active
      Type: boolean

      Whether a user is active.

      This is usually used when you send an .identify() call to update the traits independently of when you've “last seen” a user.

    • campaign
      Type: object

      Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. utm_source).

    • channel
      Type: string enum

      The channel the event originated from.

      values
      • browser
      • server
      • mobile
    • ip
      Type: string

      The user's IP address. This isn't captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).

    • locale
      Type: string

      The locale string for the current user, e.g. en-US.

    • page
      Type: object

      Contains information about the current page in the browser. This is automatically collected by our JavaScript source.

    • userAgent
      Type: string

      The user agent of the device making the request

Responses
  • 200

    A successful request returns an empty object response.

Request Example for post/batch
{
  "batch": [
    {
      "type": "identify",
      "userId": "241ma8mf4a",
      "anonymousId": "c0e5cae6-6f04-46e4-97a8-25076e8bdc0b",
      "context": {
        "active": true,
        "campaign": {
          "content": "",
          "medium": "",
          "name": "",
          "source": "",
          "term": "",
          "Additional UTM Parameters": ""
        },
        "channel": "browser",
        "ip": "",
        "locale": "",
        "page": {
          "keywords": [
            ""
          ],
          "name": "",
          "path": "",
          "referrer": "",
          "search": "",
          "title": "",
          "url": ""
        },
        "userAgent": ""
      },
      "integrations": {
        "All": true,
        "Salesforce": false
      },
      "messageId": "",
      "originalTimestamp": "",
      "sentAt": "",
      "timestamp": "",
      "traits": {
        "cio_subscription_preferences": {
          "channels": {
            "email": true,
            "push": false
          },
          "topics": {
            "topic_1": true,
            "topic_2": false
          }
        },
        "createdAt": "",
        "email": "",
        "unsubscribed": true,
        "Additional Traits": null
      }
    }
  ],
  "context": {
    "active": true,
    "campaign": {
      "content": "",
      "medium": "",
      "name": "",
      "source": "",
      "term": "",
      "Additional UTM Parameters": ""
    },
    "channel": "browser",
    "ip": "",
    "locale": "",
    "page": {
      "keywords": [
        ""
      ],
      "name": "",
      "path": "",
      "referrer": "",
      "search": "",
      "title": "",
      "url": ""
    },
    "userAgent": ""
  }
}
No Body

A successful request returns an empty object response.