--- openapi: 3.0.3 info: title: Braze REST API – Export user profile by identifier description: | ## 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. 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 security: - BearerAuth: [] paths: /users/export/ids: post: summary: Export user profile by identifier description: | ## 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. operationId: exportUsersByIdentifier requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExportUsersByIdRequest' examples: multiple_identifiers: summary: Export by several identifier types description: | You can combine identifier types in one request. Braze returns the users that match any of the identifiers. value: 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: "+15555550100" fields_to_export: - first_name - email - purchases 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 description: | Omitting `fields_to_export` returns all fields. For customers who have onboarded with Braze on or after August 22, 2024, `fields_to_export` is required, so this request returns a `400` error. value: braze_id: 5fbd99bac125ca40511f2cb1 responses: "201": description: | The request succeeded and the response body includes the exported user profiles. No action needed. For an example of the data that is accessible through this endpoint see the following example. **Tip:** For help with CSV and API exports, visit [Export troubleshooting]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting). content: application/json: schema: $ref: '#/components/schemas/ExportUsersByIdResponse' examples: full_profile: summary: Example user export file output value: message: success users: - 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 success: summary: Successful export with limited fields 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: | Bad request. To resolve it: - **An IDs value isn't an array:** Pass IDs as an array. - **More than 50 IDs were provided:** Send 50 or fewer IDs per request. - **No identifier field was provided:** Include at least one identifier field. - **The `fields_to_export` value isn't an array:** Pass `fields_to_export` as an array of field names. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ids_not_array: summary: An IDs value isn't an array value: message: external_ids and aliases must be arrays too_many_ids: summary: More than 50 IDs value: message: the max number of external_ids and aliases per request was exceeded no_identifier: summary: No identifier field value: message: "'external_ids' or 'aliases' or 'device_id' is required" invalid_fields_to_export: summary: The fields_to_export value isn't an array value: message: Invalid format of fields to export. Needs to be an array. "401": description: | Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. 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). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: summary: Invalid API key value: message: 'Invalid API key: YOUR_REST_API_KEY' "403": description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `users.export.ids` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: access_denied: summary: Missing permission value: message: Access Denied "429": description: | Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 5XX: description: | Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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: title: User alias 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: title: Field to export 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: title: Export user profile by identifier request 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 you wish to export. example: - user_identifier1 - user_identifier2 user_aliases: type: array maxItems: 50 items: $ref: '#/components/schemas/UserAlias' description: '[User aliases]({{site.baseurl}}/api/objects_filters/user_alias_object) for users to export.' device_id: type: string description: Device identifier, as returned by various SDK methods such as `getDeviceId`. example: "1234567" braze_id: type: string description: Braze identifier for a particular user. example: braze_identifier email_address: type: string format: email description: Email address of user. example: example@example.com phone: type: string description: Phone number of user, in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: "+15555550100" fields_to_export: type: array minItems: 1 description: | 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. **Note:** For customers who have onboarded with Braze on or after August 22, 2024, the request parameter `fields_to_export` is required. If you omit it or pass an empty array, the request fails with `Invalid format of fields to export. Needs to be an array.` For valid values, see [Fields to export](#fields-to-export). items: $ref: '#/components/schemas/ExportFieldName' example: - first_name - email - purchases ExportedUserPushToken: title: Push token 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. `true` means foreground push is enabled for the token, and `false` means foreground push is disabled (for example, background-only). provisionally_opted_in: type: boolean nullable: true description: | 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`. ExportedUserDevice: title: Device 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. Only included for iOS devices when IDFV collection is enabled. idfa: type: string description: iOS Identifier for Advertising, if collection is enabled. Only included for iOS devices when IDFA collection is enabled. device_id: type: string description: Braze device identifier. google_ad_id: type: string description: Android Google Play Advertising Identifier, if available. Only included for Android devices when Google Play Advertising Identifier collection is enabled. roku_ad_id: type: string description: Roku Advertising Identifier, if available. Only included for Roku devices. ad_tracking_enabled: type: boolean description: Whether ad tracking is enabled on the device. ExportedUserCustomEvent: title: Custom event 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: title: Purchase 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: title: App 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: title: Campaign engagement type: object properties: opened_email: type: boolean opened_push: type: boolean clicked_email: type: boolean clicked_triggered_in_app_message: type: boolean CampaignReceived: title: Campaign received 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 description: Exists only if it is a multivariate campaign. variation_api_id: type: string description: Exists only if it is a multivariate campaign. in_control: type: boolean description: Exists only if it is a multivariate campaign. CanvasStepReceived: title: Canvas step received type: object properties: name: type: string api_canvas_step_id: type: string last_received: type: string format: date-time CanvasReceived: title: Canvas received 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: title: Card clicked type: object properties: name: type: string description: Name of the clicked card. ExportedUser: title: User export object type: object description: | 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). 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 description: User's first name. last_name: type: string description: User's last name. email: type: string description: User's email address. dob: type: string format: date description: Date of birth in `YYYY-MM-DD` format. home_city: type: string description: User's home city. 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 nullable: true enum: [M, F, O, N, P] description: User's gender. For possible values, see [Fields to export](#fields-to-export). 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: title: Export user profile by identifier response type: object description: Returns the full user profile (or selected fields, if `fields_to_export` is provided) for the specified identifiers. required: [message] properties: message: type: string description: Export status. Returns `success` when completed. example: success users: type: array description: Exported user profile objects. May be empty if no users are found. 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: title: Error type: object properties: message: type: string description: Human-readable error message. errors: type: array description: Optional list of detailed validation errors. items: type: string