Send bulk events

API at a glance

Description: This API allows you to send multiple events in a single API call from your server or using JavaScript events. This is network-efficient and reduces the number of connections needed.

Authentication & testing

Testing the API on this page

How to try it here

Use your User API Key as the Username (leave Password blank).

Select the appropriate API endpoint based on your Blueshift region.

Enter the necessary parameters and click Try It to run the request.

Authentication using Base64 encoding

Note for developers

API requests require authentication using HTTP Basic Authentication with an API key. The API key serves as the username, while the password field should be left empty. The format to encode is: your_api_key: (note the trailing colon).

This string must be Base64-encoded and included in the request's Authorization header as follows:

Authorization: Basic encoded_value

You can generate the encoded value using a trusted Base64 encoder.

Postman collection

Try it with Postman: Explore the API using Blueshift's Postman collection.

Things to know before you start

Network efficiency: The bulk API call reduces the number of connections needed compared to individual event calls.
Bulk sending: You can send multiple events in bulk as part of an array.
Payload limits: The maximum size of a payload is 1MB or 30 events per payload.
Rate limiting: We recommend limiting the number of bulk calls to 5 per second (or 150 events/sec).
Required identifier fields: Each event must provide values for at least one of: customer_id, event, device_id, cookie, or email.
Best practice: If possible, provide values for more than one identifier field per event.
Anonymous users: For anonymous users, specify at least the value for the cookie.
Use case: Best for batch processing of events, importing historical data, or high-volume event tracking scenarios.

Request parameters

Check out the request parameters

Body parameters

Parameter	Type	Required	Description
`events`	`array`	✅ Yes	An array of event objects. Each object follows the structure below.

Event object properties

Note: Each event must provide at least one of: customer_id, event, device_id, cookie, or email.

Parameter	Type	Required	Description
`event`	`string`	✅ Yes	Specify the name of the event (e.g., `identify`, `view`, `add_to_cart`, `purchase`, `search`, custom event names).
`customer_id`	`string`	❌ No	Specify the customer ID.
`email`	`string`	❌ No	Specify the user's email address.
`device_id`	`string`	❌ No	Specify the UUID of the device.
`device_type`	`string`	❌ No	Specify the type of the device (e.g., `ios`, `android`).
`device_tokens`	`string`	❌ No	Specify the token of the device.
`device_idfa`	`string`	❌ No	Specify the advertising identifier (IDFA) on the device.
`device_idfv`	`string`	❌ No	Specify the identifier for vendor (IDFV) on the device.
`device_manufacturer`	`string`	❌ No	Specify the manufacturer of the device.
`os_name`	`string`	❌ No	Specify the OS name.
`network_carrier`	`string`	❌ No	Specify the carrier on the mobile device.
`ip`	`string`	❌ No	Specify the IP address of the device.
`latitude`	`string`	❌ No	Specify the latitude of the user's location.
`longitude`	`string`	❌ No	Specify the longitude of the user's location.
`subscription_groups`	`array`	❌ No	Specify the user's subscription preferences. See structure below.

Subscription groups object

Parameter	Type	Description
`id`	`string`	The ID of the subscription group.
`subscribed`	`boolean`	Enter `true` if the user is subscribed, or `false` if unsubscribed.

Example requests & responses

Send bulk events

Request

curl --request POST \
     --url https://api.getblueshift.com/api/v1/bulkevents \
     --header 'accept: application/json' \
     --header 'authorization: Basic <YOUR_EVENT_API_KEY>' \
     --header 'content-type: application/json' \
     --data '{
       "events": [
         {
           "customer_id": "abc812122",
           "event": "identify",
           "device_type": "ios",
           "device_tokens": "49244924492449244924492449244924492449244924",
           "device_id": "8abe3faa-d48d-4e4a-00ca-beae01f1c987",
           "device_idfa": "4d031ed8-c40e-57d4-9c99-a3e308d8cd78",
           "device_idfv": "6d031ec8-e40c-47d4-9c99-b3e308d8ed78",
           "device_manufacturer": "apple",
           "os_name": "ios",
           "network_carrier": "verizon",
           "ip": "201.44.11.21",
           "email": "[email protected]",
           "latitude": "212.99333",
           "longitude": "-12.39334",
           "subscription_groups": [
             {
               "id": "newsletter",
               "subscribed": true
             },
             {
               "id": "weekly_promo",
               "subscribed": false
             }
           ]
         },
         {
           "customer_id": "812123",
           "event": "purchase",
           "ip": "201.44.11.22",
           "email": "[email protected]",
           "revenue": "31.24"
         }
       ]
     }'

Response

{
  "status": "ok",
  "count": 2
}