API at a glance
Description: This API creates or updates multiple customers in a single request. You can process up to 50 customers per API call.
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_valueYou 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
- Batch limit: Maximum 50 customers per API call.
- Rate limit: We recommend limiting bulk calls to 5 per second (or 250 users per second).
- CRITICAL - Required identifier: Each customer object MUST have either
emailorcustomer_id. Without at least one valid identifier, the customer record will not be created or updated. Always ensure you provide valid identifiers to avoid data loss. - ⚠️ WARNING - Check response carefully: Even if the API returns 200 OK, individual customer records can fail if they're missing identifiers. The failed records will appear in the
errorsarray withuser_identifier_missingerror. Always validate your response to ensure all customers were processed successfully. - Use case: Best for bulk customer imports, batch profile updates, data migrations, and syncing customer data from external systems.
Request parameters
Check out the request parameters
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customers | array | ✅ Yes | Array of customer objects. Maximum 50 per request. |
Customer object fields
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | ✅ Yes (or customer_id) | Email address of the customer (max 64 characters). |
customer_id | string | ✅ Yes (or email) | Customer ID of the customer. |
firstname | string | ❌ No | First name of the customer. |
lastname | string | ❌ No | Last name of the customer. |
uuid | string | ❌ No | UUID of the customer (for updates). |
subscription_groups | array | ❌ No | User's subscription preferences. See structure below. |
Subscription groups object
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | ✅ Yes | ID of the subscription group. |
subscribed | boolean | ✅ Yes | true if subscribed, false if unsubscribed. |
Example requests & responses
Bulk create/update customers (Success)
{
"customers": [
{
"email": "[email protected]",
"firstname": "John",
"lastname": "Smith"
},
{
"email": "[email protected]",
"firstname": "Jane",
"lastname": "Doe"
},
{
"email": "[email protected]",
"customer_id": "CUST-12345",
"firstname": "Mike",
"lastname": "Johnson"
},
{
"customer_id": "CUST-67890",
"firstname": "Sarah",
"lastname": "Williams"
},
{
"customer_id": "CUST-11223",
"email": "[email protected]",
"firstname": "Robert",
"lastname": "Brown"
}
]
}{
"customers": [],
"errors": []
}⚠️ Error: Missing identifier (200 OK with errors)
What happens: API returns 200 OK, but customers without valid identifiers fail and appear in the errors array.
{
"customers": [
{
"email": "[email protected]",
"firstname": "John"
},
{
"customer_id": "CUST-12345",
"lastname": "Doe"
},
{
"lastname": "Williams"
}
]
}{
"customers": [
{
"lastname": "Williams",
"customer_id": null
}
],
"errors": [
{
"status": 400,
"error_data": {
"user_identifier_missing": [
"No valid identifier found"
]
}
}
]
}Prevention: Always include either email or customer_id for every customer in your request.
Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift.
Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff.
You can upload up to 50 users in an API call.
Rate limit exceeded. Too many requests. Contact us on [email protected] for recommended throughput.
Internal server error. Contact Blueshift for more information.
Service unavailable, please retry. Bad gateway. Retry with exponential backoff.
Service unavailable, please retry. Service unavailable. Retry with exponential backoff.
Service unavailable, please retry. Gateway timeout. Retry with exponential backoff.