Mass update profile
Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom ID.
Use /profiles/mass-update for large-scale periodic imports. Learn more about selecting the right endpoint here: Profile updates: choosing the right API endpoint.
API Description
Update one or multiple profile's data and track events
The unique project key, identifying a project on the Batch platform
project_0664hxvwffvbpn278gxdyhsadddqgna6Edit multiple profiles at once. You can specify at most 10 000 operations or the API call will be rejected.
POST /2.5/profiles/mass-update HTTP/1.1
Host: api.batch.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Batch-Project: text
Content-Type: application/json
Accept: */*
Content-Length: 546
[
{
"identifiers": {
"custom_id": "[email protected]"
},
"attributes": {
"$email_address": "[email protected]",
"$email_marketing": "subscribed",
"$phone_number": "+33639981337",
"$sms_marketing": "unsubscribed",
"$language": "en",
"$region": "FR",
"$timezone": "Europe/Paris",
"firstname": "Jane",
"date(birthdate)": "1989-07-20T00:00:00Z",
"interests": [
"bikes",
"cinema"
],
"reward_programs": {
"$add": [
"premium_customer"
]
}
},
"events": [
{
"name": "added_to_cart",
"attributes": {
"$label": "pumpkin",
"quantity": 5,
"unit_price": 3.99,
"$tags": [
"fruits",
"organic",
"on_sale"
]
}
}
]
}
]{
"code": "SUCCESS"
}Update one or multiple profile's data and track events
The unique project key, identifying a project on the Batch platform
project_0664hxvwffvbpn278gxdyhsadddqgna6Edit multiple profiles at once. You can specify at most 200 operations or the API call will be rejected.
POST /2.5/profiles/update HTTP/1.1
Host: api.batch.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Batch-Project: text
Content-Type: application/json
Accept: */*
Content-Length: 546
[
{
"identifiers": {
"custom_id": "[email protected]"
},
"attributes": {
"$email_address": "[email protected]",
"$email_marketing": "subscribed",
"$phone_number": "+33639981337",
"$sms_marketing": "unsubscribed",
"$language": "en",
"$region": "FR",
"$timezone": "Europe/Paris",
"firstname": "Jane",
"date(birthdate)": "1989-07-20T00:00:00Z",
"interests": [
"bikes",
"cinema"
],
"reward_programs": {
"$add": [
"premium_customer"
]
}
},
"events": [
{
"name": "added_to_cart",
"attributes": {
"$label": "pumpkin",
"quantity": 5,
"unit_price": 3.99,
"$tags": [
"fruits",
"organic",
"on_sale"
]
}
}
]
}
]Rate Limiting
To ensure fair usage and platform stability, the /profiles/mass-update endpoint is subject to rate limiting, following the Token Bucket algorithm:
API rate: Up to 10000 profile updates per second are allowed.
Burst capacity: No burst
If you exceed these limits, the API will respond with an HTTP 429 Too Many Requests error. When you receive this error, please wait a few seconds before retrying, as further attempts may continue to be rejected until your rate falls back within the allowed limits.
Note that our API rate limit is measured in updates per second.
Unlike other API rate limits which are often measured in requests per second or minute, our rate is calculated based on the number of Custom IDs processed within your requests.
What constitutes one "update"? One update corresponds to the processing associated with a single Custom ID included in your request. For example, if a request contains data for 10 different Custom IDs, it will consume 10 updates from your rate limit, regardless of the number of attributes updated or events tracked for each individual Custom ID within that same request.
This unit of measurement has been chosen to effectively manage the processing load, particularly when utilizing bulk operations. Processing multiple Custom IDs in a single bulk request is more efficient, and tracking the rate by the number of IDs processed (updates) ensures fair usage and system stability under heavy load from bulk submission.
Request structure
Route
The Profile API exposes a POST endpoint that allows to update a batch of profiles:
https://api.batch.com/2.4/profiles/mass-update
You can update one or several profiles via this endpoint, within the limit of 10 000 profiles.
Headers and authentication
See Overview → Using Project APIs.
See Update profile for more details & examples on the request payload & error management.
Failure
If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at [email protected] if you need further support.
AUTHENTICATION_INVALID(HTTP status code: 401, error_code: 10)ROUTE_NOT_FOUND(HTTP status code: 404, error_code: 20)MISSING_PARAMETER(HTTP status code: 400, error_code: 30)MALFORMED_PARAMETER(HTTP status code: 400, error_code: 31)MALFORMED_JSON_BODY(HTTP status code: 400, error_code: 32)SERVER_ERROR(HTTP status code: 500, error_code: 1)MAINTENANCE_ERROR(HTTP status code: 503, error_code: 2)TOO_MANY_REQUESTS(HTTP status code: 429, error_code: 60)
If you get a "too many requests" response, please wait for at least 5 seconds before trying again. Further requests might still return this error.
{
"error_code": "MALFORMED_PARAMETER",
"error_message": "Invalid project key project_062ay7ywmgvqccwanj647mmqm1smq2k"
}Last updated
Was this helpful?