---
openapi: 3.0.3
info:
title: Braze REST API – Export user profile by identifier
description: |
Export data from any user profile by specifying a user identifier.
Up to 50 `external_ids` or `user_aliases` can be included per request. Only
one `device_id`, `email_address`, or `phone` can be included per request.
For customers who onboarded with Braze on or after August 22, 2024, the
`fields_to_export` parameter is required.
For help with CSV and API exports, see
[Export troubleshooting](https://www.braze.com/docs/user_guide/data/distribution/export_braze_data/export_troubleshooting/).
version: 1.0.0
contact:
name: Braze Support
url: https://www.braze.com/docs/braze_support/
license:
name: Braze Documentation
url: https://www.braze.com/docs/api/home/
servers:
- url: https://rest.iad-01.braze.com
description: US-01
- url: https://rest.iad-02.braze.com
description: US-02
- url: https://rest.iad-03.braze.com
description: US-03
- url: https://rest.iad-04.braze.com
description: US-04
- url: https://rest.iad-05.braze.com
description: US-05
- url: https://rest.iad-06.braze.com
description: US-06
- url: https://rest.iad-07.braze.com
description: US-07
- url: https://rest.iad-08.braze.com
description: US-08
- url: https://rest.us-10.braze.com
description: US-10
- url: https://rest.fra-01.braze.eu
description: EU-01
- url: https://rest.fra-02.braze.eu
description: EU-02
- url: https://rest.au-01.braze.com
description: AU-01
- url: https://rest.id-01.braze.com
description: ID-01
- url: https://rest.jp-01.braze.com
description: JP-01
- url: https://rest.kr-01.braze.com
description: KR-01
tags:
- name: Export
description: Access and export user profile data.
security:
- BearerAuth: []
paths:
/users/export/ids:
post:
summary: Export user profile by identifier
description: |
Returns the full user profile (or selected fields, if `fields_to_export`
is provided) for the specified identifiers. Requires a REST API key with
the `users.export.ids` permission.
**Rate limit:** 250 requests per minute by default; 40 requests per
second when `fields_to_export` is provided.
Because this endpoint pulls together the entire user profile, it is
slower than other REST endpoints. For large exports, prefer
`/users/export/segment`.
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `users.export.ids` permission.
## Rate limit
If you onboarded with Braze on or after August 22, 2024, this endpoint has a rate limit of 250 requests per minute, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
You can also increase this endpoint's rate limit to 40 requests per second by meeting the following requirements:
- Your workspace has the default rate limit (250 requests per minute) enabled. Contact your Braze account manager for further assistance with removing any pre-existing rate limit you may have.
- Your request includes the `fields_to_export` parameter to list out all the fields you want to receive.
**Important:** If you include `canvases_received` or `campaigns_received` in the `fields_to_export` parameter, your request will be ineligible for the faster rate limit. We recommend only including these in your request if you have a specific use case for them.
## Request body
```
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
```
```json
{
"external_ids": (optional, array of strings) External identifiers for users you wish to export,
"user_aliases": (optional, array of user alias objects) user aliases for users to export,
"device_id": (optional, string) Device identifier as returned by various SDK methods such as `getDeviceId`,
"braze_id": (optional, string) Braze identifier for a particular user,
"email_address": (optional, string) Email address of user,
"phone": (optional, string) Phone number of user,
"fields_to_export": (optional, array of strings) Name of user data fields to export
}
```
**Note:**
For customers who have onboarded with Braze on or after August 22, 2024, the request parameter `fields_to_export` is required.
## Request parameters
| Parameter | Required | Data Type | Description |
| ------------------ | -------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `external_ids` | Optional | Array of strings | External identifiers for users you wish export. |
| `user_aliases` | Optional | Array of user alias object | [User aliases]({{site.baseurl}}/api/objects_filters/user_alias_object) for users to export. |
| `device_id` | Optional | String | Device identifier, as returned by various SDK methods such as `getDeviceId`. |
| `braze_id` | Optional | String | Braze identifier for a particular user. |
| `email_address` | Optional | String | Email address of user. |
| `phone` | Optional | String in [E.164](https://en.wikipedia.org/wiki/E.164) format | Phone number of user. |
| `fields_to_export` | Optional* | Array of strings | Name of user data fields to export.
*This field is required to use the faster rate limit of 40 requests per second. If omitted, the default rate limit of 250 requests per min will be used instead. |
*Required for customers who have onboarded with Braze on or after August 22, 2024.
## Example request
```
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/ids' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"external_ids": ["user_identifier1", "user_identifier2"],
"user_aliases": [
{
"alias_name": "example_alias",
"alias_label": "example_label"
}
],
"device_id": "1234567",
"braze_id": "braze_identifier",
"email_address": "example@example.com",
"phone": "11112223333",
"fields_to_export": ["first_name", "email", "purchases"]
}'
```
## Response
```json
{
"message": (string) returns 'success' when the request completes 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 through this endpoint see the following example.
### Example 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 or empty):
```json
{
"created_at": (string),
"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) ISO-3166-1 alpha-2 standard,
"phone" : (string),
"language" : (string) ISO-639-1 standard,
"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 when IDFV collection is enabled,
"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,
"ad_tracking_enabled" : (boolean)
},
...
],
"push_tokens" : [
{
"app" : (string) app name,
"platform" : (string),
"token" : (string),
"device_id": (string),
"notifications_enabled": (boolean) whether foreground push notifications are enabled for this token. `true` means foreground push is enabled for the token, and `false` means foreground push is disabled (for example, background-only). This is device-level and doesn't indicate the user's global push subscription status,
"provisionally_opted_in": (boolean) included for iOS and Android tokens only. Indicates whether the token is in a provisional push authorization state. `true` means the token is provisionally opted in (notifications are delivered quietly), `false` means the token isn't provisional (the user has explicitly authorized or denied push), and `null` means provisional status isn't set. Provisional authorization applies to iOS; Android tokens report `null`
},
...
],
"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" : (boolean),
"opened_push" : (boolean),
"clicked_email" : (boolean),
"clicked_triggered_in_app_message" : (boolean)
},
"converted" : (boolean),
"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, boolean) 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": (boolean),
"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)
},
...
]
}
```
```json
{
"created_at" : "2020-07-10 15:00:00.000 UTC",
"external_id" : "A8i3mkd99",
"user_aliases" : [
{
"alias_name" : "user_123",
"alias_label" : "amplitude_id"
}
],
"braze_id": "5fbd99bac125ca40511f2cb1",
"random_bucket" : 2365,
"first_name" : "Alex",
"last_name" : "Smith",
"email" : "example@example.com",
"dob" : "1980-12-21",
"home_city" : "Chicago",
"country" : "US",
"phone" : "+15555550123",
"language" : "en",
"time_zone" : "Eastern Time (US & Canada)",
"last_coordinates" : [41.84157636433568, -87.83520818508256],
"gender" : "F",
"total_revenue" : 65,
"attributed_campaign" : "braze_test_campaign_072219",
"attributed_source" : "braze_test_source_072219",
"attributed_adgroup" : "braze_test_adgroup_072219",
"attributed_ad" : "braze_test_ad_072219",
"push_subscribe" : "opted_in",
"push_opted_in_at": "2020-01-26T22:45:53.953Z",
"email_subscribe" : "subscribed",
"custom_attributes":
{
"loyaltyId": "37c98b9d-9a7f-4b2f-a125-d873c5152856",
"loyaltyPoints": "321",
"loyaltyPointsNumber": 107
},
"custom_events": [
{
"name": "Loyalty Acknowledgement",
"first": "2021-06-28T17:02:43.032Z",
"last": "2021-06-28T17:02:43.032Z",
"count": 1
},
...
],
"purchases": [
{
"name": "item_40834",
"first": "2021-09-05T03:45:50.540Z",
"last": "2022-06-03T17:30:41.201Z",
"count": 10
},
...
],
"devices": [
{
"model": "Pixel XL",
"os": "Android (Q)",
"carrier": null,
"device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
"ad_tracking_enabled": true
},
...
],
"push_tokens": [
{
"app": "MovieCanon",
"platform": "Android",
"token": "12345abcd",
"device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
"notifications_enabled": true,
"provisionally_opted_in": null
},
...
],
"apps": [
{
"name": "MovieCannon",
"platform": "Android",
"version": "3.29.0",
"sessions": 1129,
"first_used": "2020-02-02T19:56:19.142Z",
"last_used": "2021-11-11T00:25:19.201Z"
},
...
],
"campaigns_received": [
{
"name": "Email Unsubscribe",
"api_campaign_id": "d72fdc84-ddda-44f1-a0d5-0e79f47ef942",
"last_received": "2022-06-02T03:07:38.105Z",
"engaged":
{
"opened_email": true
},
"converted": true,
"multiple_converted":
{
"Primary Conversion Event - A": true
},
"in_control": false,
"variation_name": "Variant 1",
"variation_api_id": "1bddc73a-a134-4784-9134-5b5574a9e0b8"
},
...
],
"canvases_received": [
{
"name": "Non Global Holdout Group 4/21/21",
"api_canvas_id": "46972a9d-dc81-473f-aa03-e3473b4ed781",
"last_received_message": "2021-07-07T20:46:24.136Z",
"last_entered": "2021-07-07T20:45:24.000+00:00",
"variation_name": "Variant 1",
"in_control": false,
"last_entered_control_at": null,
"steps_received": [
{
"name": "Step",
"api_canvas_step_id": "43d1a349-c3c8-4be1-9fbe-ce708e4d1c39",
"last_received": "2021-07-07T20:46:24.136Z"
},
...
]
}
...
],
"cards_clicked" : [
{
"name" : "Loyalty Promo"
},
...
]
}
```
**Tip:**
For help with CSV and API exports, visit [Export troubleshooting]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting).
## 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:
| Field to export | Data type | Description |
| --------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps` | Array | Apps this user has logged sessions for, which includes the fields:
- `name`: app name
- `platform`: app platform, such as iOS, Android, or Web
- `version`: app version number or name
- `sessions`: total number of sessions for this app
- `first_used`: date of first session
- `last_used`: date of last session
All fields are strings. |
| `attributed_campaign` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration), if set up. Identifier for a particular ad campaign. |
| `attributed_source` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration), if set up. Identifier for the platform the ad was on. |
| `attributed_adgroup` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration), if set up. Identifier for an optional sub-grouping below campaign. |
| `attributed_ad` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration), if set up. Identifier for an optional sub-grouping below campaign and ad group. |
| `push_subscribe` | String | User's push subscription status. |
| `email_subscribe` | String | User's email subscription status. |
| `braze_id` | String | Device-specific unique user identifier set by Braze for this user. |
| `country` | String | User's country using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. |
| `created_at` | String | Date and time for when the user profile was created, in ISO 8601 format. |
| `custom_attributes` | Object | Custom attribute key-value pairs for this user. |
| `custom_events` | Array | Custom events attributed to this user in the last 90 days. |
| `devices` | Array | Information about the user's device, which could include the following depending on platform:
- `model`: Device's model name
- `os`: Device's operating system
- `carrier`: Device's service carrier, if available
- `idfv`: (iOS) Braze device identifier, the Apple Identifier for Vendor, if exists
- `idfa`: (iOS) Identifier for Advertising, if exists
- `device_id`: (Android) Braze device identifier
- `google_ad_id`: (Android) Google Play Advertising Identifier, if exists
- `roku_ad_id`: (Roku) Roku Advertising Identifier
- `ad_tracking_enabled`: If ad tracking is enabled on the device, can be true or false |
| `dob` | String | User's date of birth in the format `YYYY-MM-DD`. |
| `email` | String | User's email address. |
| `external_id` | String | Unique user identifier for identified users. |
| `first_name` | String | User's first name. |
| `gender` | String | User's gender. Possible values are:
- `M`: male
- `F`: female
- `O`: other
- `N`: not applicable
- `P`: prefer not to say
- `nil`: unknown |
| `home_city` | String | User's home city. |
| `language` | String | User's language in ISO-639-1 standard. |
| `last_coordinates` | Array of floats | User's most recent device location, formatted as `[longitude, latitude]`. |
| `last_name` | String | User's last name. |
| `phone` | String | User's telephone number in E.164 format. |
| `purchases` | Array | Purchases this user has made in the last 90 days. |
| `push_tokens` | Array | Unique anonymous identifier that specifies where to send an app's notifications. |
| `random_bucket` | Integer | User's [random bucket number]({{site.baseurl}}/user_guide/data/distribution/braze_currents/event_glossary/customer_behavior_events), used to create uniformly distributed segments of random users. |
| `time_zone` | String | User's time zone in the same format as the IANA Time Zone Database. |
| `total_revenue` | Float | Total revenue attributed to this user. Total revenue is calculated based on purchases the user made during conversion windows for the campaigns and Canvases they received. |
| `uninstalled_at` | Timestamp | Date and time the user uninstalls the app. Omitted if the app has not been uninstalled. |
| `user_aliases` | Object | [User aliases object]({{site.baseurl}}/api/objects_filters/user_alias_object) containing the `alias_name` and `alias_label`, if exists. |
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 not be sufficient to meet your needs due to the 250 requests per minute 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.
## Response status codes
The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it.
| Status code | Meaning | Error message | How to resolve |
| --- | --- | --- | --- |
| `201 Created` | The request succeeded and the response body includes the exported user profiles. | `success` | No action needed. |
| `400 Bad Request` | An IDs value isn't an array. | `ids must be an array` | Pass IDs as an array. |
| `400 Bad Request` | More than 50 IDs were provided. | `the max number of ids per request was exceeded` | Send 50 or fewer IDs per request. |
| `400 Bad Request` | No identifier field was provided. | `external_ids, appboy_ids, braze_ids, user_aliases, email_addresses, or phone numbers is required` | Include at least one identifier field. |
| `400 Bad Request` | More than one identifier type was provided. | `only one of either external_ids, appboy_ids, braze_ids, user_aliases, email_addresses, or phone_numbers can be included` | Include only one identifier type per request. |
| `400 Bad Request` | The `fields_to_export` value isn't an array. | `Invalid format of fields to export. Needs to be an array.` | Pass `fields_to_export` as an array of field names. |
| `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). |
| `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `users.export.ids` permission. |
| `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). |
| `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). |
operationId: exportUsersByIdentifier
tags:
- Export
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExportUsersByIdRequest'
examples:
by_external_id:
summary: Export by external_id with limited fields
value:
external_ids:
- user_identifier_1
fields_to_export:
- first_name
- email
- custom_attributes
by_user_alias:
summary: Export by user_alias
value:
user_aliases:
- alias_name: example_alias
alias_label: example_label
fields_to_export:
- external_id
- email
by_email:
summary: Export by email_address
value:
email_address: jane.doe@example.com
fields_to_export:
- first_name
- last_name
- email
all_fields:
summary: Export all fields by braze_id
value:
braze_id: 5fbd99bac125ca40511f2cb1
responses:
"200":
description: User export data.
content:
application/json:
schema:
$ref: '#/components/schemas/ExportUsersByIdResponse'
examples:
success:
summary: Successful export
value:
message: success
users:
- created_at: "2020-07-10T15:00:00.000Z"
external_id: A8i3mkd99
braze_id: 5fbd99bac125ca40511f2cb1
first_name: Jane
last_name: Doe
email: jane.doe@example.com
country: US
language: en
time_zone: Eastern Time (US & Canada)
push_subscribe: opted_in
email_subscribe: subscribed
custom_attributes:
loyaltyPoints: 321
no_results:
summary: No matching users
value:
message: success
users: []
invalid_user_ids:
- unknown_external_id
"400":
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_request:
value:
message: 'one of "external_ids", "user_aliases", "device_id", "braze_id", "email_address", or "phone" is required'
"401":
description: Unauthorized – the API key is missing, invalid, or lacks the `users.export.ids` permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
value:
message: invalid_api_key
"429":
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
rate_limited:
value:
message: rate_limited
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: REST API key
description: |
REST API keys are created in the Braze dashboard at **Settings → APIs and
Identifiers → API Keys**. The key must include the `users.export.ids`
permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
schemas:
UserAlias:
type: object
required: [alias_name, alias_label]
properties:
alias_name:
type: string
description: The alias value.
example: example_alias
alias_label:
type: string
description: The alias label.
example: example_label
ExportFieldName:
type: string
enum:
- 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
description: |
Valid values for `fields_to_export`:
- `apps`: App usage metadata (`name`, `platform`, `version`, `sessions`, `first_used`, `last_used`)
- `attributed_campaign`: Campaign identifier from attribution integrations
- `attributed_source`: Source/platform identifier from attribution integrations
- `attributed_adgroup`: Ad group identifier from attribution integrations
- `attributed_ad`: Ad identifier from attribution integrations
- `braze_id`: Braze user identifier
- `campaigns_received`: Campaign delivery and engagement history
- `canvases_received`: Canvas delivery and step history
- `cards_clicked`: Content Card clicks
- `country`: Country code (ISO 3166-1 alpha-2)
- `created_at`: User profile creation time (ISO 8601)
- `custom_attributes`: Custom user attributes
- `custom_events`: Custom events from the last 90 days
- `devices`: Device metadata
- `dob`: Date of birth (`YYYY-MM-DD`)
- `email`: Email address
- `email_subscribe`: Email subscription status
- `external_id`: External user identifier
- `first_name`: First name
- `gender`: Gender (`M`, `F`, `O`, `N`, or `P`)
- `home_city`: Home city
- `language`: Language code (ISO 639-1)
- `last_coordinates`: Last known coordinates as `[longitude, latitude]`
- `last_name`: Last name
- `phone`: Phone number in E.164 format
- `purchases`: Purchases from the last 90 days
- `push_subscribe`: Push subscription status
- `push_tokens`: Push token metadata
- `random_bucket`: Random bucket number for uniform segmentation
- `time_zone`: Time zone
- `total_revenue`: Total attributed revenue
- `uninstalled_at`: App uninstall timestamp (if available)
- `user_aliases`: User aliases
ExportUsersByIdRequest:
type: object
description: |
At least one identifier (`external_ids`, `user_aliases`, `device_id`,
`braze_id`, `email_address`, or `phone`) is required.
properties:
external_ids:
type: array
maxItems: 50
items:
type: string
description: External identifiers for users to export.
user_aliases:
type: array
maxItems: 50
items:
$ref: '#/components/schemas/UserAlias'
description: User aliases for users to export.
device_id:
type: string
description: Device identifier, returned by SDK methods such as `getDeviceId`.
braze_id:
type: string
description: Braze identifier for a specific user profile.
email_address:
type: string
format: email
description: Email address of the user to export.
phone:
type: string
description: Phone number in E.164 format.
example: "+15555550100"
fields_to_export:
type: array
description: |
Names of user fields to include in the response.
For customers who onboarded with Braze on or after August 22, 2024,
this field is required.
items:
type: string
enum:
- 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
ExportedUserPushToken:
type: object
description: Push token metadata for a device.
properties:
app:
type: string
description: App name.
platform:
type: string
description: Platform for this token.
token:
type: string
description: Push token value.
device_id:
type: string
description: Device identifier associated with the token.
notifications_enabled:
type: boolean
description: |
Whether foreground push notifications are enabled for this token.
This is a device-level setting and does not represent global user
subscription status.
ExportedUserDevice:
type: object
description: Device metadata for the user profile.
properties:
model:
type: string
description: Device model.
os:
type: string
description: Device operating system.
carrier:
type: string
nullable: true
description: Device carrier, when available.
idfv:
type: string
description: iOS Identifier for Vendor, if collection is enabled.
idfa:
type: string
description: iOS Identifier for Advertising, if collection is enabled.
device_id:
type: string
description: Braze device identifier.
google_ad_id:
type: string
description: Android Google Play Advertising Identifier, if available.
roku_ad_id:
type: string
description: Roku Advertising Identifier, if available.
ad_tracking_enabled:
type: boolean
description: Whether ad tracking is enabled on the device.
ExportedUserCustomEvent:
type: object
description: Summary of a custom event in the last 90 days.
properties:
name:
type: string
first:
type: string
format: date-time
description: First time this event was observed.
last:
type: string
format: date-time
description: Most recent time this event was observed.
count:
type: integer
description: Number of times this event was observed.
ExportedUserPurchase:
type: object
description: Summary of a purchase in the last 90 days.
properties:
name:
type: string
first:
type: string
format: date-time
description: First time this purchase was observed.
last:
type: string
format: date-time
description: Most recent time this purchase was observed.
count:
type: integer
description: Number of times this purchase was observed.
ExportedUserApp:
type: object
description: App usage metadata for a profile.
properties:
name:
type: string
platform:
type: string
description: App platform, such as iOS, Android, or Web.
version:
type: string
sessions:
type: integer
description: Total sessions for this app.
first_used:
type: string
format: date-time
last_used:
type: string
format: date-time
CampaignEngagement:
type: object
properties:
opened_email:
type: boolean
opened_push:
type: boolean
clicked_email:
type: boolean
clicked_triggered_in_app_message:
type: boolean
CampaignReceived:
type: object
description: Campaign delivery and engagement summary.
properties:
name:
type: string
last_received:
type: string
format: date-time
engaged:
$ref: '#/components/schemas/CampaignEngagement'
converted:
type: boolean
multiple_converted:
type: object
additionalProperties:
type: boolean
description: Conversion status by conversion event name.
api_campaign_id:
type: string
variation_name:
type: string
variation_api_id:
type: string
in_control:
type: boolean
CanvasStepReceived:
type: object
properties:
name:
type: string
api_canvas_step_id:
type: string
last_received:
type: string
format: date-time
CanvasReceived:
type: object
description: Canvas delivery and participation summary.
properties:
name:
type: string
api_canvas_id:
type: string
last_received_message:
type: string
format: date-time
last_entered:
type: string
format: date-time
variation_name:
type: string
in_control:
type: boolean
last_entered_control_at:
type: string
format: date-time
nullable: true
steps_received:
type: array
items:
$ref: '#/components/schemas/CanvasStepReceived'
CardClicked:
type: object
properties:
name:
type: string
description: Name of the clicked card.
ExportedUser:
type: object
description: |
Fields are omitted when the underlying value is null or empty. When
`fields_to_export` is provided, only the requested fields are returned.
properties:
created_at:
type: string
format: date-time
description: Date and time the user profile was created.
external_id:
type: string
description: Unique identifier for identified users.
user_aliases:
type: array
description: User aliases for this profile.
items:
$ref: '#/components/schemas/UserAlias'
braze_id:
type: string
description: Braze identifier for this user profile.
first_name:
type: string
last_name:
type: string
email:
type: string
dob:
type: string
format: date
description: Date of birth in `YYYY-MM-DD` format.
home_city:
type: string
country:
type: string
description: Country code in ISO 3166-1 alpha-2 format.
phone:
type: string
description: Phone number in E.164 format.
language:
type: string
description: Language code in ISO 639-1 format.
time_zone:
type: string
description: IANA time zone identifier.
last_coordinates:
type: array
minItems: 2
maxItems: 2
description: Most recent device location as `[longitude, latitude]`.
items:
type: number
format: float
gender:
type: string
enum: [M, F, O, N, P]
total_revenue:
type: number
format: float
description: Total revenue attributed to this user.
attributed_campaign:
type: string
description: Campaign identifier from attribution integrations.
attributed_source:
type: string
description: Source identifier from attribution integrations.
attributed_adgroup:
type: string
description: Ad group identifier from attribution integrations.
attributed_ad:
type: string
description: Ad identifier from attribution integrations.
push_subscribe:
type: string
enum: [opted_in, subscribed, unsubscribed]
description: Push subscription state.
push_opted_in_at:
type: string
format: date-time
description: Timestamp when push was opted in.
email_subscribe:
type: string
enum: [opted_in, subscribed, unsubscribed]
description: Email subscription state.
custom_attributes:
type: object
description: Custom attribute key-value pairs for this user.
additionalProperties: true
custom_events:
type: array
description: Custom events attributed to this user in the last 90 days.
items:
$ref: '#/components/schemas/ExportedUserCustomEvent'
purchases:
type: array
description: Purchases attributed to this user in the last 90 days.
items:
$ref: '#/components/schemas/ExportedUserPurchase'
devices:
type: array
description: Device metadata for this user.
items:
$ref: '#/components/schemas/ExportedUserDevice'
push_tokens:
type: array
description: Push token metadata for this user.
items:
$ref: '#/components/schemas/ExportedUserPushToken'
apps:
type: array
description: Apps this user has session activity for.
items:
$ref: '#/components/schemas/ExportedUserApp'
campaigns_received:
type: array
description: Campaign delivery and engagement history.
items:
$ref: '#/components/schemas/CampaignReceived'
canvases_received:
type: array
description: Canvas delivery and step history.
items:
$ref: '#/components/schemas/CanvasReceived'
cards_clicked:
type: array
description: Content Cards clicked by this user.
items:
$ref: '#/components/schemas/CardClicked'
random_bucket:
type: integer
description: Random bucket number used for uniform segmentation.
uninstalled_at:
type: string
format: date-time
description: Time when the app was uninstalled, if available.
ExportUsersByIdResponse:
type: object
required: [message]
properties:
message:
type: string
description: Export status. Returns `success` when completed.
example: success
users:
type: array
description: Exported user profile objects.
items:
$ref: '#/components/schemas/ExportedUser'
invalid_user_ids:
type: array
items:
type: string
description: Identifiers from the request that did not match known users.
ErrorResponse:
type: object
properties:
message:
type: string
errors:
type: array
items:
type: string