Skip to content

Standard attributes

Standard attributes are predefined fields that Braze recognizes on every user profile. Use this page as a quick reference for the field name, data type, and expected format of each standard attribute.

Standard attributes (sometimes called default attributes or reserved keys) are different from custom attributes, which are unique to your business. When you send data to Braze with one of the field names listed on this page, Braze stores it on the predefined profile field instead of creating a new custom attribute.

You can set standard attributes through any of these methods:

Identifiers

Identifiers tell Braze which user profile to update or create. Every API request and CSV row must include at least one identifier. For details on choosing the right one, see Identifier resolution.

Profile fields

These fields capture demographic, contact, and locale data about your users.

These fields manage how a user receives messages across channels. Updating them does not count toward your data point usage.

For details on subscription group setup, see Subscription groups.

Sessions and engagement

These fields capture when the user first or last engaged with your app. The SDK records them automatically; you typically set them only through API or CSV when migrating from another platform.

Push tokens

Use these fields when migrating push tokens from another platform. After you integrate the Braze SDK, push tokens are captured automatically. For migration guidance, see Migrating push tokens.

Social profile

These fields store data from social network integrations.

API example

The following request sets standard attributes on two users through the /users/track endpoint.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "attributes": [
    {
      "external_id": "user1",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "time_zone": "America/New_York",
      "dob": "1988-02-14",
      "email_subscribe": "opted_in"
    },
    {
      "external_id": "user2",
      "first_name": "Alex",
      "phone": "+14155552671",
      "current_location": {
        "longitude": -73.991443,
        "latitude": 40.753824
      },
      "subscription_groups": [
        {
          "subscription_group_id": "abc-123",
          "subscription_state": "subscribed"
        }
      ]
    }
  ]
}

For the full API contract, see the User attributes object.

CSV example

The following CSV updates standard attributes for two users. Column headers must exactly match the field names in this article. Headers that don’t match (for example, First_name instead of first_name) are imported as custom attributes.

1
2
3

external_id,first_name,last_name,email,country,language,dob,email_subscribe
user1,Jane,Doe,[email protected],US,en,1988-02-14,opted_in
user2,Alex,Smith,[email protected],GB,en,1992-09-30,subscribed

You can’t set some standard attributes through CSV import. You must send arrays, push tokens, and nested objects through the API or Cloud Data Ingestion instead. For the complete list of CSV-supported fields and import steps, see Default attributes.

Considerations

Consider these points when working with standard attributes:

  • Field names are case sensitive. Always use lowercase. A header or key that doesn’t exactly match a standard attribute name is treated as a custom attribute.
  • SDK auto-capture is suppressed when you set values through API or CSV. When you set country or language through API or CSV, Braze stops auto-capturing those fields from the SDK for that user.
  • null removes a value. Set a standard attribute to null to remove it from the profile. Some fields, including external_id and user_alias, can’t be removed after they’re set.
  • Blank CSV values don’t overwrite. A blank cell in a CSV import keeps the existing value on the profile. To clear a value, use the API.
  • Time zones default to UTC. Date strings without an offset are interpreted as midnight UTC and displayed in your workspace’s time zone. To specify a time zone, append a UTC offset (for example, 2024-11-10T18:00:00-05:00).
New Stuff!