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

Mass Update

post

Update one or multiple profile's data and track events

Authorizations

rest_key

AuthorizationstringRequired

API Key Authentication

Authentication is required in order to interact with Batch's APIs.

Batch implements authentication using API Keys, that we call the "REST API Key". You can find it on your dashboard.

Please make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would easily be extractable.

How to authenticate

In order to authenticate your requests, add your REST API Key in the Authorization header and prefix it by Bearer. Example: Authorization: Bearer bcd38d9rfb38ra28.

Header parameters

X-Batch-ProjectstringRequired

The unique project key, identifying a project on the Batch platform

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Bodyobject[]

application/json

Edit multiple profiles at once. You can specify at most 10 000 operations or the API call will be rejected.

Responses

202

Request accepted, will be processed asynchronously

application/json

400

The request is malformed

application/json

401

The Rest API Key is not valid for this project

application/json

429

Too Many Requests

application/json

500

Unexpected error

application/json

503

Batch's services are under maintenance. Please try again later

application/json

post

/profiles/mass-update

HTTPcURLJavaScriptPython

POST /2.8/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: 587

[
  {
    "identifiers": {
      "custom_id": "[e-mail]"
    },
    "attributes": {
      "$email_address": "[e-mail]",
      "$email_marketing": "subscribed",
      "$phone_number": "[phone]",
      "$sms_marketing": "unsubscribed",
      "$language": "en",
      "$region": "FR",
      "$timezone": "Europe/Paris",
      "$email_open_tracking_consent": "granted",
      "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

post

Update one or multiple profile's data and track events

Authorizations

rest_key

AuthorizationstringRequired

API Key Authentication

Authentication is required in order to interact with Batch's APIs.

Batch implements authentication using API Keys, that we call the "REST API Key". You can find it on your dashboard.

Please make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would easily be extractable.

How to authenticate

In order to authenticate your requests, add your REST API Key in the Authorization header and prefix it by Bearer. Example: Authorization: Bearer bcd38d9rfb38ra28.

Header parameters

X-Batch-ProjectstringRequired

The unique project key, identifying a project on the Batch platform

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Bodyobject[]

application/json

Edit multiple profiles at once. You can specify at most 200 operations or the API call will be rejected.

post

/profiles/update

HTTPcURLJavaScriptPython

POST /2.8/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: 587

[
  {
    "identifiers": {
      "custom_id": "[e-mail]"
    },
    "attributes": {
      "$email_address": "[e-mail]",
      "$email_marketing": "subscribed",
      "$phone_number": "[phone]",
      "$sms_marketing": "unsubscribed",
      "$language": "en",
      "$region": "FR",
      "$timezone": "Europe/Paris",
      "$email_open_tracking_consent": "granted",
      "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:

/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 [e-mail] 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"
}