POST - Update profile

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

The Profile API allows you to update profiles, use this endpoint to:

Set attributes
Track events
Set email subscription status and email address
Set phone subscription status and phone number
Set a timezone
Set a language & region

A profile is automatically created if no existing profiles match the id in the payload of your call.

API Description

This API schema is available in the OpenAPI 3.1 format: View it online.

Request structure

Route

The Profile API exposes a POST endpoint that allows to update a batch of profiles:

https://api.batch.com/2.1/profiles/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.

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": "jane_doe@batch-store.com"
    },
    "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": "jane_doe@batch-store.com"
    }
  },
  {
    "identifiers": {
      "custom_id": "92bec35f-07fa-42d9-b676-74bb165dd018"
    },
    "attributes": {
      "$email_address": "bo_b@gmail.com"
    }
  }
]

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).

Id	Description
`custom_id`	String - Mandatory Custom ID of the profile you would like to update. Max 512 chars and case sensitive. E.g.`{"custom_id":"129c7819-9c88-496e-9a5f-62db34a3ce61"}`

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": "jane.doe@demobatch.com",
      "$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"
        ]
      }
}

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.

Id	Description
`$email_address`	String - Optional Email address. Null to erase, omit to leave the email unmodified. Addresses must be valid, not longer than 256 characters. It must match the following pattern: ^[^\r\n\t@]+@[A-z0-9\-\.]+\.[A-z0-9]+$ E.g.`{"$email_address":"jane.doe@demobatch.com"}`
`$email_marketing`	String - Optional The profile's marketing emails subscription. You can set it to subscribed , unsubscribed , or null to reset the marketing emails subscription. Note that profile's subscription status is automatically set to unsubscribed when they click an unsubscribe link. E.g.`{"$email_marketing":"subscribed"}`
`$phone_number`	String - Optional Phone mumber. Null to erase, omit to leave the phone number unmodified. The phone number must conform to the E.164 international standard . E.g.`{"$phone_number":"+33639981337"}`
`$sms_marketing`	String - Optional The profile's marketing SMS subscription. You can set it to subscribed , unsubscribed , or null to reset the marketing SMS subscription. E.g.`{"$sms_marketing":"unsubscribed"}`
`$language`	String - Optional The profile's language. See supported language codes here. E.g.`{"$language":"fr"}`
`$region`	String - Optional The profile's region. See supported region codes here. E.g.`{"$region":"FR"}`
`$timezone`	String - Optional The profile's timezone. See supported timezone codes here. E.g.`{"$timezone":"Europe/Paris"}`

Custom attributes

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

Key names should 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 64 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.

{
  "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 64 chars. 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"
    ]
}

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.

Id	Description
`name`	String - Mandatory The event's name. Max 30chars E.g.`{"name":"added_to_cart"}`
`time`	Date - Optional The time an event occurred. It has to respect the RFC 3339 format. You can track events that happened in the last 24 hours, and no events in the future. If this parameter is not included in your request, Batch will use the time the event arrives at the server. Time is accepted in TS format in seconds and RFC 3339 format (2012-08-12T22:30:05Z) E.g.`{"time":"2023-10-02T16:32:39+00:00"}`
`attributes`	Object - Optional An object containing all event's attributes. Max 25kb. E.g.`{"attributes":{"unit_price":3.99}}`

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

String

String types attributes cannot be empty or over 200 characters, they can be null.

{"firstname": "Jane"}

Array

You can set array of strings (max 200chars) 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"
        ]
      }
    }
  ]
}

Object

Objects cannot have more than 3 levels of nesting.

{
  "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.

Id	Description
`$label`	String - Optional Max 200 chars. E.g.`{"$label":"clothing"}`
`$tags`	Array - Optional Max 10 items of type string, each no longer than 64chars E.g.`{"$tags":["first_purchase","in_promo"]}`

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 support@batch.com 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?

Personalization features based on objects and arrays of objects will be released in 2024.

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 support@batch.com 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.

Next stepExport profile data

Documentation > API > Profile API

POST - Update profile

API Description

Request structure

Route

Headers and authentication

Update profile

The identifiers object

The attributes object

Native attributes

Custom attributes

String

Integer

Float

Date

URL

Boolean

String arrays

The events object

The events attributes object

String

Array

Object

Reserved event attributes

Responses

Success

Success with partial errors

Failure

Frequently asked questions

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

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

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?