Users by Identifier Endpoint
/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.
Looking for the api_key
parameter?
As of May 2020, Braze has changed how we read API keys to be more secure. Now API keys must be passed as a request header, please see YOUR_REST_API_KEY
within the Example Request below.
Braze will continue to support the api_key
being passed through the request body and URL parameters, but will eventually be sunset. Please update your API calls accordingly.
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)
},
...
]
}
For help with CSV and API exports, visit our troubleshooting article here.