Update profile

Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom ID.

Use /profiles/update for continuous streams and rapid processing of small batches where quick data ingestion is key. Learn more about selecting the right endpoint here: Profile updates: choosing the right API endpoint.

API Description

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/update endpoint is subject to rate limiting, following the Token Bucket algorithm:

• API rate: Up to 300 profile updates per second are allowed.

• Burst capacity: The API allows short bursts of up to 1000 profile updates (tokens) at once, if your bucket is full.

• 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 profile 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/update

You can update one or several profiles via this endpoint, within the limit of 200 profiles.

Headers and authentication

See Overview → Using Project APIs.

Update profile

The body of the request must contain a valid JSON payload describing the update operations to execute for a set of given Custom IDs.

[
  {
    "identifiers": {
      "custom_id": "129c7819-9c88-496e-9a5f-62db34a3ce61"
    },
    "attributes": {
      "$email_address": "[e-mail]"
    },
    "events": [
      {
        "name": "validated_purchase",
        "attributes": {
          "delivery_address": {
            "number": 43,
            "street": "Rue Beaubourg",
            "zip_code": 75003,
            "city": "Paris",
            "country": "France"
          },
          "items_list": [
            {
              "name": "Basic Tee",
              "size": "M",
              "price": 23.99,
              "url(item_url)": "https://batch-store.com/basic-tee",
              "url(item_image)": "https://batch-store.com/basic-tee/black/image.png",
              "in_sales": true
            },
            {
              "name": "Short socks pack x3",
              "size": "38-40",
              "price": 15.99,
              "url(item_url)": "https://batch-store.com/short-socks-pack-x3",
              "url(item_image)": "https://batch-store.com/short-socks-pack-x3/image.png",
              "in_sales": false
            }
          ],
          "metadata": [
            "first_purchase",
            "apple_pay"
          ]
        }
      }
    ]
  }
]

To update multiple profiles at the same time:

[
  {
    "identifiers": {
      "custom_id": "129c7819-9c88-496e-9a5f-62db34a3ce61"
    },
    "attributes": {
      "$email_address": "[e-mail]"
    }
  },
  {
    "identifiers": {
      "custom_id": "92bec35f-07fa-42d9-b676-74bb165dd018"
    },
    "attributes": {
      "$email_address": "[e-mail]"
    }
  }
]

The identifiers object

The identifiers object allows you to indicate which profile you need to update, it has the following form:

"identifiers": {
    "custom_id": "129c7819-9c88-496e-9a5f-62db34a3ce61"
}

Batch supports sending attributes and events using the Custom ID, this custom identifier can be:

• The unique ID you are using in your login system.

• A stable ID used in your data store (e.g. Firebase, etc).

• Any stable information that can help you to identify a user (e.g. hashed email address, etc).

The attributes object

The Profile API allows you to set and update native and custom profile attributes in the attributes object. It has the following form:

"attributes": {
      "$email_address": "[e-mail]",
      "$email_marketing": "subscribed",
      "$phone_number": "[phone]",
      "$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"
        ]
      }
}

Attribute keys refer to the names of the attributes. Set the attribute value by providing its name (key) and the value associated. You can set up to 50 attributes per profile per operation: requests exceeding this limit will be ignored. Some keys are documented as they're reserved. This object cannot weigh more than 25kB or the entire Profile API request will be rejected.

Native attributes

Native attributes have reserved keys, and are all prefixed by a $ sign. This is the list of currently supported native attributes. You cannot set an attribute starting by a $ sign.

Custom attributes

You can also set custom attributes, with a name and a value.

Key names must be made of letters, numbers or underscores ([a-z0-9_]). They cannot be longer than 30 characters and cannot contain uppercase characters.

The following value types are supported:

• String

• Integer

• Float

• Date

• URL

• Boolean

• String arrays

String

String types attributes cannot be empty or over 300 characters, they can be null. Setting a string to null completely removes this attribute from the profile.

{"firstname": "Jane"}

Integer

Integer attributes are supported and can be null. Setting an integer to null completely removes this attribute from the profile.

{"age": 25}

Float

Float attributes are supported and can be null. Setting a float to null completely removes this attribute from the profile.

{"level_progress": 25.5}

Date

JSON does not support date natively. Therefore, we require additional information to identify an attribute as a date. This is achieved by wrapping the attribute key in the date() function.

Dates are accepted in TS format in seconds and RFC 3339 format (2012-08-12T22:30:05Z).

{
  "date(promo_starts)": 1451642400,
  "date(promo_ends)": "2012-08-12T22:30:05Z"
}

URL

URL type is also supported. You will need to wrap the key name in the url() function.

Values must be valid URLs and no longer than 2048 characters:

• A scheme is compulsory (myapp://, https://...)

• :// is compulsory after the scheme

{
  "url(product_image)": "https://batchstore/product/4729/image.png",
  "url(product_deeplink)": "myapp://path/to/content"
}

Boolean

Boolean attributes can be true, false or null.

{
  "is_premium": false
}

String arrays

Arrays of strings are supported at a profile level. A string in an array cannot be longer than 300 chars. When updating a profile via the API, a string array can contain up to 25 attributes per request. You can:

• set directly all attributes of an array

• add an attribute to an array, with $add

• remove an attribute from an array, with $remove

• delete an array from a profile by setting its value to null

If some attribute is invalid in the array, the whole array will be rejected and not set on the profile.

You can add an attribute to a non-existing array, Batch will automatically create the array if it doesn't exist yet on the targeted profile.

Using the $add function will replace any existing attributes with the same name by an array with the set array item. If you use the $remove operation, it will delete the attribute from the profile.

"interests": ["bikes","cinema"],
"reward_programs": {
    "$add": [
        "premium_customer"
    ]
}

Limits and Behavior: A string array attribute stored in a Profile can contain up to 1500 attributes in total. When this limit is exceeded, the oldest attributes are automatically removed to keep the array at 1500 elements. Arrays of strings have the following properties:

• Uniqueness of elements.

• Deterministic order: when an element is added, it is placed at the end of the array; if it already existed, it is moved to the end.

Deleting an attribute

To delete an attribute, set its value to null:

"firstname": null,
"promo_starts": null,

Date/URL attributes are deleted in the same way and must not have their name wrapped in date()/url().

The events object

The events object contains all events to track on the profile. It cannot weigh more than 125kB or contain more than 15 events. You can set up to 15 events per profile per API call. If one of these limits is exceeded, the whole Profile API call will be rejected.

The events attributes object

The event attributes object allows you to attach additional attributes to an event, it cannot me more than 25kB.

It has the following structure:

"attributes": {
  "items_list": [
    {
      "name": "Basic Tee",
      "size": "M",
      "price": 23.99,
      "url(item_url)": "https://batch-store.com/basic-tee",
      "url(item_image)": "https://batch-store.com/basic-tee/image.png",
      "in_sales": true
      },
      {
        "name": "Short socks pack x3",
        "size": "38-40",
        "price": 15.99,
        "url(item_url)": "https://batch-store.com/short-socks-pack-x3",
        "url(item_image)": "https://batch-store.com/short-socks-pack-x3/image.png",
        "in_sale": false
      }
    ],
    "delivery_address": {
      "number": 43,
      "street": "Rue Beaubourg",
      "zip_code": 75003,
      "city": "Paris",
      "country": "France"
    },
    "metadata": [
      "first_purchase",
      "quick_buy"
    ]
  }

The following value types are supported:

• String

• Number

• Float

• Date

• URL

• Array

• Object

All types except for Array & Object behave as they do in profile attributes.

Object

Objects can be used to group attributes. They cannot have more than 3 levels of nesting, both objects and array count as one level of nesting.

{
  "events": [
    {
      "name": "validated_purchase",
      "attributes": {
        "delivery_address": {
          "number": 43,
          "street": "Rue Beaubourg",
          "zip_code": 75003,
          "city": "Paris",
          "country": "France"
        }
      }
    }
  ]
}

Array

You can set array of strings (max 300 characters) and array of objects. You cannot mix several attribute types in one array. Arrays can't be nested.

{
  "events": [
    {
      "name": "validated_purchase",
      "attributes": {
        "items_list": [
          {
            "name": "Basic Tee",
            "size": "M",
            "price": 23.99,
            "url(item_url)": "https://batch-store.com/basic-tee",
            "url(item_image)": "https://batch-store.com/basic-tee/black/image.png",
            "in_sales": true
          },
          {
            "name": "Short socks pack x3",
            "size": "38-40",
            "price": 15.99,
            "url(item_url)": "https://batch-store.com/short-socks-pack-x3",
            "url(item_image)": "https://batch-store.com/short-socks-pack-x3/image.png",
            "in_sales": false
          }
        ],
        "metadata": [
          "first_purchase",
          "apple_pay"
        ]
      }
    }
  ]
}

Reserved event attributes

Some event attributes have reserved keys, and are all prefixed by a $ sign. This is the list of currently reserved event attributes. You cannot set an event attribute starting by a $ sign.

In the Trigger Events API, you were able to set a label and tags at the root of an event, with the limit of 1 label and 10 tags.

With the Profile API and the introduction of the array type in event attributes, you can set more that one array on profiles events. This is only supported for profiles, and not on the install centric data model, which currently powers push notification and In-App messages.

However, it's still possible to set a label and tags on events in the install centric data model by using $label and $tags, and activate compatibility flows. This way, you will be able to use this data for your push and in-app communications.

Responses

Success

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation. This means the API call was entirely valid and will be processed as requested.

HTTP Status Code: 202

Response:
{
  "code": "SUCCESS"
}

Success with partial errors

If your API calls has non fatal errors, you will receive an HTTP 202 confirmation and details about the non fatal errors. Data that isn't listed in the errors array will be processed.

HTTP Status Code: 202

{
    "code": "SUCCESS_WITH_PARTIAL_ERRORS",
    "errors": [
        {
            "category": "attribute",
            "bulk_index": 0,
            "reason": "Array attributes must not contain empty string item",
            "attribute": "array"
        }
    ]
}

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"
}

Frequently asked questions

How can I see that the profile data is correctly updated during implementation?

The Profile view page of the dashboard displays profiles in real-time so you can review your implementation.

How can I use objects and arrays of objects in message personalization?

See the Message personalization documentation.

Is the Profile API compatible with the installation based data model? Can I use the Profile API to send data and use it for push notifications and in-app messages?

Emails are sent on the base of profiles, whereas push notifications & In-App messages are sent on an app-based userbase made of installations.

By default, the Profile API only updates the profile base which is used to send email messages. However, compatibility flows are available to allow you to feed all user data with the Profile API, including the install centric userbase. Compatibility flows are set up by Batch team, reach out to [e-mail] for more information.

If you send more than 15 attributes in one event, only the first 15 event attributes (alphabetical order) will be written on the install centric userbase. If you would like to set a label and tags, use the compatibility attributes $label and $tags.