Users by Identifier Endpoint

post

/users/export/ids

This endpoint allows you to export data from any user profile by specifying a form of user identifier. Up to 50 external_ids or user_aliases can be included in a single request. Should you want to specify device_id or email_address only one of either identifier can be included per request.

Test me with Swagger
See me in Postman

Request Body

1
2

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
7
8
9
10
11
12

{
  "external_ids": ["user_id1", "user_id2"],
  "user_aliases": {
    "alias_name": "",
    "alias_label": ""
  },
  "device_id": "123456",
  "braze_id": "braze_user_id",
  "email_address": "email_example@braze.com",
  "phone": "+12223334444",
  "fields_to_export": ["first_name", "email", "purchases"]
}

Request Parameters

Key Requirement Data Type Details
external_ids Optional Array of Strings External ids for users to export
user_aliases Optional Array of User Alias Object. User aliases for users to export
device_id Optional String Device ID as returned by various SDK methods such as getDeviceId
braze_id Optional String Braze ID for a particular user
email_address Optional String Email address of a user
fields_to_export Optional Array of Strings Name of user data fields to export. Defaults to all if not provided

Request Component

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl --location --request POST 'https://rest.iad-01.braze.com/users/export/ids' \
--header 'Content-Type: application/json' \
--data-raw '{
  "external_ids": ["user_id1", "user_id2"],
  "user_aliases": {
    "alias_name": "",
    "alias_label": ""
  },
  "device_id": "123456",
  "braze_id": "braze_user_id",
  "email_address": "email_example@braze.com",
  "phone": "+12223334444",
  "fields_to_export": ["first_name", "email", "purchases"]
}'

Fields to Export

The following is a list of valid fields_to_export. Using fields_to_export to minimize the data returned can improve response time of this API endpoint:

  • apps
  • attributed_campaign
  • attributed_source
  • attributed_adgroup
  • attributed_ad
  • braze_id
  • campaigns_received
  • canvases_received
  • cards_clicked
  • country
  • created_at
  • custom_attributes
  • custom_events
  • devices
  • dob
  • email
  • email_subscribe
  • external_id
  • first_name
  • gender
  • home_city
  • language
  • last_coordinates
  • last_name
  • phone
  • purchases
  • push_subscribe
  • push_tokens
  • random_bucket
  • time_zone
  • total_revenue
  • uninstalled_at
  • user_aliases

Please be aware that the /users/export/ids endpoint will pull together the entire user profile for this user, including data such as all campaigns and canvases received, all custom events performed, all purchases made, and all custom attributes. As a result, this endpoint is slower than other REST API endpoints.

Depending on the data requested, this API endpoint may have not be able to fulfill your hourly API rate limit. If you anticipate using this endpoint regularly to export users, instead consider exporting users by segment, which is asynchronous and more optimized for larger data pulls. Documentation on that endpoint is below.

Response

1
2
3
4
5
6
7

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "users" : (array of object) the data for each of the exported users, may be empty if no users are found,
    "invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user
}

For an example of the data that is accessible via this endpoint see the example below.

Sample User Export File Output

User export object (we will include the least data possible - if a field is missing from the object it should be assumed to be null, false, or empty):

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

{
    "external_id" : (string),
    "user_aliases" : [
      {
        "alias_name" : (string),
        "alias_label" : (string)
      }
    ],
    "braze_id": (string),
    "first_name" : (string),
    "last_name" : (string),
    "email" : (string),
    "dob" : (string) date for the user's date of birth,
    "home_city" : (string),
    "country" : (string),
    "phone" : (string),
    "language" : (string) ISO-639 two letter code,
    "time_zone" : (string),
    "last_coordinates" : (array of float) [lon, lat],
    "gender" : (string) "M" | "F",
    "total_revenue" : (float),
    "attributed_campaign" : (string),
    "attributed_source" : (string),
    "attributed_adgroup" : (string),
    "attributed_ad" : (string),
    "push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "custom_attributes" : (object) custom attribute key value pairs,
    "custom_events" : [
        {
            "name" : (string),
            "first" : (string) date,
            "last" : (string) date,
            "count" : (int)
        },
        ...
    ],
    "purchases" : [
        {
            "name" : (string),
            "first" : (string) date,
            "last" : (string) date,
            "count" : (int)
        },
        ...
    ],
    "devices" : [
        {
            "model" : (string),
            "os" : (string),
            "carrier" : (string),
            "idfv" : (string) only included for iOS devices,
            "idfa" : (string) only included for iOS devices when IDFA collection is enabled,
            "google_ad_id" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled,
            "roku_ad_id" : (string) only included for Roku devices,
            "windows_ad_id" : (string) only included for Windows devices,
            "ad_tracking_enabled" : (bool)
        },
        ...
    ],
    "push_tokens" : [
        {
            "app" : (string) app name,
            "platform" : (string),
            "token" : (string)
        },
        ...
    ],
    "apps" : [
        {
            "name" : (string),
            "platform" : (string),
            "version" : (string),
            "sessions" : (integer),
            "first_used" : (string) date,
            "last_used" : (string) date
        },
        ...
    ],
    "campaigns_received" : [
        {
            "name" : (string),
            "last_received" : (string) date,
            "engaged" : {
                "opened_email" : (bool),
                "opened_push" : (bool),
                "clicked_email" : (bool),
                "clicked_triggered_in_app_message" : (bool)
            },
            "converted" : (bool),
            "api_campaign_id" : (string),
            "variation_name" : (optional, string) exists only if it is a multivariate campaign,
            "variation_api_id" : (optional, string) exists only if it is a multivariate campaign,
            "in_control" : (optional, bool) exists only if it is a multivariate campaign
        },
        ...
    ],
    "canvases_received": [
        {
            "name": (string),
            "api_canvas_id": (string),
            "last_received_message": (string) date,
            "last_entered": (string) date,
            "variation_name": (string),
            "in_control": (bool),
            "last_exited": (string) date,
            "steps_received": [
                {
                    "name": (string),
                    "api_canvas_step_id": (string),
                    "last_received": (string) date
                },
                {
                    "name": (string),
                    "api_canvas_step_id": (string),
                    "last_received": (string) date
                },
                {
                    "name": (string),
                    "api_canvas_step_id": (string),
                    "last_received": (string) date
                }
            ]
        },
        ...
    ],
    "cards_clicked" : [
        {
            "name" : (string)
        },
        ...
    ]
}
  Edit this page on GitHub
WAS THIS PAGE HELPFUL?
New Stuff!