---
openapi: 3.0.3
info:
title: Braze REST API – Export user profile by Global Control Group
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `users.export.global_control_group` permission.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
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/global_control_group:
post:
summary: Export user profile by Global Control Group
description: |
## Credentials-based response details
If you have added your [S3]({{site.baseurl}}/partners/data_and_analytics/cloud_storage/amazon_s3/) or [Azure]({{site.baseurl}}/partners/data_and_analytics/cloud_storage/microsoft_azure_blob_storage_for_currents/) credentials to Braze through the respective **Technology Partners** page, then each file is uploaded in your bucket as a ZIP file with the key format that looks like `segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip`. If using Azure, make sure that you have the **Make this the default data export destination** box checked in the Azure partner overview page in Braze.
Generally, we create one file per 5,000 users to optimize processing. Exporting smaller segments within a large workspace may result in multiple files. You can then extract the files and concatenate all of the `json` files to a single file if needed. If you specify an `output_format` of `gzip`, then the file extension is `.gz` instead of `.zip`.
### Export pathing breakdown for ZIP
**ZIP format:**
`bucket-name/segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip`
**Example ZIP:**
`braze.docs.bucket/segment-export/abc56c0c-rd4a-pb0a-870pdf4db07q/2019-04-25/d9696570-dfb7-45ae-baa2-25e302r2da27-1556044807/114f0226319130e1a4770f2602b5639a.zip`
| Property | Details | Shown in Example as |
| ------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------- |
| `bucket-name` | Fixed based on your bucket name. | `braze.docs.bucket` |
| `segment-export` | Fixed. | `segment-export` |
| `SEGMENT_ID` | Included in the export request. | `abc56c0c-rd4a-pb0a-870pdf4db07q` |
| `YYYY-MM-dd` | The date the successful callback is received. | `2019-04-25` |
| `RANDOM_UUID` | A random UUID generated by Braze at the time of the request. | `d9696570-dfb7-45ae-baa2-25e302r2da27` |
| `TIMESTAMP_WHEN_EXPORT_STARTED` | Unix time (seconds since 2017-01-01:00:00:00Z) that the export was requested in UTC. | `1556044807` |
| `filename` | Random per file. | `114f0226319130e1a4770f2602b5639a` |
We strongly suggest setting up your own S3 or Azure credentials (by going to **Partner Integrations** > **Technology Partners** > partner page) when using this endpoint to enforce your own bucket policies on the export.
If you do not have your cloud storage credentials provided, the response to the request provides the URL where a ZIP containing all the user files can be downloaded. The URL becomes a valid location only after the export is ready.
Be aware that if you do not provide your cloud storage credentials, there is a limitation on the amount of data that you can export from this endpoint. Depending on the fields you're exporting and the number of users, the file transfer may fail if it is too large. A best practice is to specify which fields you want to export using `fields_to_export` and specifying only the fields you need in order to keep the size of the transfer lower. If you are getting errors generating the file, consider breaking your user base up into more segments based on a random bucket number (for example, create a segment where random bucket number is less than 1,000 or between 1,000 and 2,000).
In either scenario, you may optionally provide a `callback_endpoint` to be notified when the export is ready. If the `callback_endpoint` is provided, we make a post request to the provided address when the download is ready. The body of the post is `"success":true`. If you haven't added your cloud storage credentials to Braze, the body of the post additionally has the attribute `url` with the download URL as the value.
Larger user bases will result in longer export times. For example, an app with 20 million users could take an hour or more.
## 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. |
| `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. |
| `random_bucket` | Integer | User's [random bucket number]({{site.baseurl}}/user_guide/data/distribution/braze_currents/event_glossary/customer_behavior_events#random-bucket-number-update-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. |
## Example user export file output
User export object (we include the least data possible—if a field is missing from the object it should be assumed to be null or empty):
### All fields
The following sample request body shows an example for All fields.
```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),
"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" : (bool)
},
...
],
"apps" : [
{
"name" : (string),
"platform" : (string),
"version" : (string),
"sessions" : (string),
"first_used" : (string) date,
"last_used" : (string) date
},
...
]
}
```
### Sample output
The following sample request body shows an example for Sample output.
```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" : "Jane",
"last_name" : "Doe",
"email" : "jane.doe@example.com",
"dob" : "1980-12-21",
"home_city" : "Chicago",
"country" : "US",
"phone" : "+15551234567",
"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",
"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
},
...
],
"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"
},
...
]
}
```
operationId: post_users_export_global_control_group_post_users_global_control_group
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExportGlobalControlGroupRequest'
examples:
example_request:
summary: Example request
value:
callback_endpoint: https://example.com/export-callback
fields_to_export:
- email
- braze_id
output_format: zip
responses:
2XX:
description: |
The request was accepted and the export was queued. No action needed.
After the URL is made available, it is valid for only a few hours. As such, we highly recommend that you add your own S3 credentials to Braze.
content:
application/json:
schema:
$ref: '#/components/schemas/UsersGlobalControlGroupResponse'
examples:
braze_hosted:
summary: Export queued, download URL returned
value:
message: success
object_prefix: bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599
url: https://example.com/segment-export/bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599.zip
cloud_storage:
summary: Export queued to your cloud storage
value:
message: success
object_prefix: bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599
"400":
description: |
Bad request. To resolve it:
- **No global control group is assigned for this workspace:** Assign a global control group before requesting this export.
- **The `fields_to_export` value isn't an array:** Pass `fields_to_export` as an array of field-name strings.
- **The `custom_attributes_to_export` value isn't formatted correctly:** Pass `custom_attributes_to_export` as an array of custom attribute names.
- **You requested more than 500 custom attributes:** Request 500 or fewer custom attributes.
- **Exporting specific custom attributes is disabled for this workspace:** Remove `custom_attributes_to_export`, or contact [Support]({{site.baseurl}}/braze_support/) to enable it.
- **The `callback_endpoint` isn't a valid URL:** Provide a valid URL for `callback_endpoint`, or omit it.
- **The `output_format` value isn't supported:** Set `output_format` to `zip` or `gzip`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
not_assigned:
summary: No Global Control Group assigned
value:
message: Global control group is not assigned
invalid_fields_to_export:
summary: fields_to_export isn't an array
value:
message: Invalid format of fields to export. Needs to be an array.
invalid_custom_attributes_to_export:
summary: custom_attributes_to_export isn't formatted correctly
value:
message: Invalid format of custom attributes to export.
too_many_custom_attributes:
summary: More than 500 custom attributes
value:
message: Number of custom attributes cannot exceed 500
custom_attributes_disabled:
summary: Exporting specific custom attributes is disabled
value:
message: Exporting specific custom attributes is disabled.
invalid_callback_url:
summary: Invalid callback_endpoint
value:
message: Invalid callback URL.
invalid_output_format:
summary: Unsupported output_format
value:
message: Invalid file output_format
"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.global_control_group` permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
access_denied:
summary: Missing permission
value:
message: Access Denied
"429":
description: |
Too many requests. To resolve it:
- **A global control group export is already in progress:** Wait for the in-progress export to finish, then retry.
- **Too many exports are already running for this workspace:** Wait for in-progress exports to finish, then retry.
- **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'
examples:
currently_exporting:
summary: Global Control Group export already in progress
value:
message: Global control group is currently exporting
too_many_exports:
summary: Too many exports in progress
value:
message: Too many exports currently in progress.
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.global_control_group` permission.
Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
schemas:
ExportGlobalControlGroupRequest:
title: Export Global Control Group request
type: object
required: [fields_to_export]
properties:
callback_endpoint:
type: string
format: uri
description: Endpoint to post a download URL to when the export is available.
example: https://example.com/export-callback
fields_to_export:
type: array
items:
type: string
description: |
Name of user data fields to export, you may also export custom attributes.
*Beginning April 2021, new accounts must specify specific fields to export.
See [Fields to export](#fields-to-export) for the fields you can export.
**Warning:**
Individual custom attributes cannot be exported. However, all custom attributes can be exported by including custom_attributes in the fields_to_export array (for example, `['first_name', 'email', 'custom_attributes']`).
example:
- first_name
- email
- purchases
output_format:
type: string
enum: [zip, gzip]
default: zip
description: When using your own S3 bucket, allows to specify file format as `zip` or `gzip`. Defaults to ZIP file format.
example: zip
UsersGlobalControlGroupResponse:
title: Export Global Control Group response
type: object
required: [object_prefix]
properties:
message:
type: string
description: Returns `success` when the request completes without errors.
example: success
object_prefix:
type: string
description: The prefix of the exported file names, used to locate the export output, for example, `bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599`. Braze uses it as the filename prefix for the JSON files produced by this export.
example: bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599
url:
type: string
nullable: true
description: The URL the export can be downloaded from. Null when the workspace hosts its own exports, in which case the files are written to your own storage.
ErrorResponse:
title: Error
type: object
properties:
message:
type: string
description: The error message describing why the request failed.
errors:
type: array
description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed.
items:
type: object
properties:
type:
type: string
description: The error type.