BrazeEx.Api.ExportUsers (braze_ex v1.0.22)

API calls for all endpoints tagged ExportUsers.

Link to this section Summary

Functions

Export User Profile by Global Control Group

Use this endpoint to export all users within a Global Control Group.

Export User Profile by Identifier

Use this endpoint to export data from any user profile by specifying a user identifier.

Export User Profile by Segment

Use this endpoint to export all the users within a segment.

Link to this section Functions

Link to this function

users_export_global_control_group_post(connection, opts \\ [])

@spec users_export_global_control_group_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

export-user-profile-by-global-control-group

Export User Profile by Global Control Group

Use this endpoint to export all users within a Global Control Group.

User data is exported as multiple files of user JSON objects separated by new lines (such as one JSON object per line).

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’]).

To use this endpoint, you’ll need to generate an API key with the users.export.global_control_group permission.

rate-limit

Rate limit

We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

credential-based-response-details

Credential-based response details

For information regarding credentials-based response details, visit this section in the Braze API docs.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
callback_endpointOptionalStringEndpoint to post a download URL to when the export is available.
fields_to_exportRequired*Array of stringsName of user data fields to export, you may also export custom attributes. <br> <br>*Beginning April 2021, new accounts must specify specific fields to export.
output_formatOptionalStringWhen using your own S3 bucket, allows to specify file format as zip or gzip. Defaults to ZIP file format.

fields-to-export

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 exportData typeDescription
appsArrayApps this user has logged sessions for, which includes the fields: <br> <br>- name: app name <br>- platform: app platform, such as iOS, Android, or Web <br>- version: app version number or name <br>- sessions: total number of sessions for this app <br>- first_used: date of first session <br>- last_used: date of last session <br> <br>All fields are strings.
attributed_campaignStringData from attribution integrations, if set up. Identifier for a particular ad campaign.
attributed_sourceStringData from attribution integrations, if set up. Identifier for the platform the ad was on.
attributed_adgroupStringData from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign.
attributed_adStringData from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign and adgroup.
braze_idStringDevice-specific unique user identifier set by Braze for this user.
countryStringUser's country using ISO 3166-1 alpha-2 standard.
created_atStringDate and time for when the user profile was created, in ISO 8601 format.
custom_attributesObjectCustom attribute key-value pairs for this user.
custom_eventsArrayCustom events attributed to this user in the last 90 days.
devicesArrayInformation about the user's device, which could include the following depending on platform: <br> <br>- model: Device's model name <br>- os: Device's operating system <br>- carrier: Device's service carrier, if available <br>- idfv: (iOS) Braze's device identifier, the Apple Identifier for Vendor, if exists <br>- idfa: (iOS) Identifier for Advertising, if exists <br>- device_id: (Android) Braze's device identifier <br>- google_ad_id: (Android) Google Play Advertising Identifier, if exists <br>- roku_ad_id: (Roku) Roku Advertising Identifier <br>- ad_tracking_enabled: If ad tracking is enabled on the device, can be true or false
dobStringUser's date of birth in the format YYYY-MM-DD.
emailStringUser's email address.
external_idStringUnique user identifier for identified users.
first_nameStringUser's first name.
genderStringUser's gender. Possible values are: <br> <br>- M: male <br>- F: female <br>- O: other <br>- N: not applicable <br>- P: prefer not to say <br>- nil: unknown
home_cityStringUser's home city.
languageStringUser's language in ISO-639-1 standard.
last_coordinatesArray of floatsUser's most recent device location, formatted as [longitude, latitude].
last_nameStringUser's last name.
phoneStringUser's telephone number in E.164 format.
purchasesArrayPurchases this user has made in the last 90 days.
random_bucketIntegerUser's random bucket number, used to create uniformly distributed segments of random users.
time_zoneStringUser's time zone in the same format as the IANA Time Zone Database.
total_revenueFloatTotal 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_atTimestampDate and time the user uninstalls the app. Omitted if the app has not been uninstalled.
user_aliasesObjectUser aliases object containing the alias_name and alias_label, if exists.

response

Response

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "message": (required, string) the status of the export, returns 'success' when completed without errors,
  "object_prefix": (required, string) the filename prefix that will be used for the JSON file produced by this export, e.g.,'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599',
  "url" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials
}

Once made available, the URL will only be valid for a few hours. As such, we highly recommend that you add your own S3 credentials to Braze.

sample-user-export-file-output

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):

{
  "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

Sample output

{
{
  "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" : "example@braze.com",
  "dob" : "1980-12-21",
  "home_city" : "Chicago",
  "country" : "US",
  "phone" : "+442071838750",
  "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"
    },
    ...
  ],
}

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

users_export_ids_post(connection, opts \\ [])

@spec users_export_ids_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

export-user-profile-by-identifier

Export User Profile by Identifier

Use this endpoint to export data from any user profile by specifying a 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.

To use this endpoint, you’ll need to generate an API key with the users.export.ids permission.

rate-limit

Rate limit

For customers who onboarded with Braze on or after August 16, 2021, we apply a rate limit of 2,500 requests per minute to this endpoint, as documented in API rate limits.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
external_idsOptionalArray of stringsExternal identifiers for users you wish export.
user_aliasesOptionalArray of user alias objectUser aliases for users to export.
device_idOptionalStringDevice identifier, as returned by various SDK methods such as getDeviceId.
braze_idOptionalStringBraze identifier for a particular user.
email_addressOptionalStringEmail address of user.
phoneOptionalString in E.164 formatPhone number of user.
fields_to_exportOptionalArray of stringsName of user data fields to export. Defaults to all if not provided.

fields-to-export

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 exportData typeDescription
appsArrayApps this user has logged sessions for, which includes the fields: <br> <br>- name: app name <br>- platform: app platform, such as iOS, Android, or Web <br>- version: app version number or name <br>- sessions: total number of sessions for this app <br>- first_used: date of first session <br>- last_used: date of last session <br> <br>All fields are strings.
attributed_campaignStringData from attribution integrations, if set up. Identifier for a particular ad campaign.
attributed_sourceStringData from attribution integrations, if set up. Identifier for the platform the ad was on.
attributed_adgroupStringData from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign.
attributed_adStringData from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign and adgroup.
braze_idStringDevice-specific unique user identifier set by Braze for this user.
countryStringUser's country using ISO 3166-1 alpha-2 standard.
created_atStringDate and time for when the user profile was created, in ISO 8601 format.
custom_attributesObjectCustom attribute key-value pairs for this user.
custom_eventsArrayCustom events attributed to this user in the last 90 days.
devicesArrayInformation about the user's device, which could include the following depending on platform: <br> <br>- model: Device's model name <br>- os: Device's operating system <br>- carrier: Device's service carrier, if available <br>- idfv: (iOS) Braze's device identifier, the Apple Identifier for Vendor, if exists <br>- idfa: (iOS) Identifier for Advertising, if exists <br>- device_id: (Android) Braze's device identifier <br>- google_ad_id: (Android) Google Play Advertising Identifier, if exists <br>- roku_ad_id: (Roku) Roku Advertising Identifier <br>- ad_tracking_enabled: If ad tracking is enabled on the device, can be true or false
dobStringUser's date of birth in the format YYYY-MM-DD.
emailStringUser's email address.
external_idStringUnique user identifier for identified users.
first_nameStringUser's first name.
genderStringUser's gender. Possible values are: <br> <br>- M: male <br>- F: female <br>- O: other <br>- N: not applicable <br>- P: prefer not to say <br>- nil: unknown
home_cityStringUser's home city.
languageStringUser's language in ISO-639-1 standard.
last_coordinatesArray of floatsUser's most recent device location, formatted as [longitude, latitude].
last_nameStringUser's last name.
phoneStringUser's telephone number in E.164 format.
purchasesArrayPurchases this user has made in the last 90 days.
random_bucketIntegerUser's random bucket number, used to create uniformly distributed segments of random users.
time_zoneStringUser's time zone in the same format as the IANA Time Zone Database.
total_revenueFloatTotal 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_atTimestampDate and time the user uninstalls the app. Omitted if the app has not been uninstalled.
user_aliasesObjectUser aliases 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 2,500 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

Response

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 following example.

sample-user-export-file-output

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):

{
  "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" : (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)
    },
    ...
  ]
}

Sample output

{
  "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" : "example@braze.com",
  "dob" : "1980-12-21",
  "home_city" : "Chicago",
  "country" : "US",
  "phone" : "+442071838750",
  "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
    },
    ...
  ],
  "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,
      "last_exited": "2021-07-07T20:46:24.136Z",
      "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.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

users_export_segment_post(connection, opts \\ [])

@spec users_export_segment_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

export-user-profile-by-segment

Export User Profile by Segment

Use this endpoint to export all the users within a segment.

Important
Beginning December 2021, the following changed for this API: <br> <br>1. The fields_to_export field in this API request is required. The option to default to all fields has been removed. <br>2. The fields for custom_events, purchases, campaigns_received, and canvases_received only contain data from the last 90 days.

User data is exported as multiple files of user JSON objects separated by new lines (such as one JSON object per line). Data is exported to an automatically generated URL, or to an S3 bucket if this integration is already set up. This endpoint is currently not supported by Google Cloud Storage.

A company may run at most one export per segment using this endpoint at a given time. Wait for your export to complete before retrying.

Note: If you are using our older navigation, segment_id can be found at Developer Console > API Settings.

To use this endpoint, you’ll need to generate an API key with the users.export.segment permission.

rate-limit

Rate limit

We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

credential-based-response-details

Credential-based response details

For information regarding credentials-based response details, visit this section in the Braze API docs.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
segment_idRequiredStringIdentifier for the segment to be exported. See segment identifier. <br> <br>The segment_id for a given segment can be found on the API Keys page within your Braze account or you can use the Segment List Endpoint.
callback_endpointOptionalStringEndpoint to post a download URL to when the export is available.
fields_to_exportRequired*Array of stringsName of user data fields to export, you may also export custom attributes. <br> <br>*Beginning April 2021, new accounts must specify specific fields to export.
custom_attributes_to_exportOptionalArray of stringsName of specific custom attribute to export. Up to 500 custom attributes can be exported. To create and manage custom attributes in the dashboard, go to Data Settings > Custom Attributes.
output_formatOptionalStringWhen using your own S3 bucket, allows you to specify file format as zip or gzip. Defaults to ZIP file format.

If custom_attributes is included in the fields_to_export parameter, all custom attributes are exported regardless of what is in custom_attributes_to_export. If your goal is to export specific attributes, custom_attributes should not be included in the fields_to_export parameter. Instead, use the custom_attributes_to_export parameter.

fields-to-export

Fields to export

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

Field to exportData typeDescription
appsArrayApps this user has logged sessions for, which includes the fields: <br> <br>- name: app name <br>- platform: app platform, such as iOS, Android, or Web <br>- version: app version number or name <br>- sessions: total number of sessions for this app <br>- first_used: date of first session <br>- last_used: date of last session <br> <br>All fields are strings.
attributed_campaignStringData from attribution integrations, if set up. Identifier for a particular ad campaign.
attributed_sourceStringData from attribution integrations, if set up. Identifier for the platform the ad was on.
attributed_adgroupStringData from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign.
attributed_adStringData from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign and adgroup.
braze_idStringDevice-specific unique user identifier set by Braze for this user.
countryStringUser's country using ISO 3166-1 alpha-2 standard.
created_atStringDate and time for when the user profile was created, in ISO 8601 format.
custom_attributesObjectCustom attribute key-value pairs for this user.
custom_eventsArrayCustom events attributed to this user in the last 90 days.
devicesArrayInformation about the user's device, which could include the following depending on platform: <br> <br>- model: Device's model name <br>- os: Device's operating system <br>- carrier: Device's service carrier, if available <br>- idfv: (iOS) Braze's device identifier, the Apple Identifier for Vendor, if exists <br>- idfa: (iOS) Identifier for Advertising, if exists <br>- device_id: (Android) Braze's device identifier <br>- google_ad_id: (Android) Google Play Advertising Identifier, if exists <br>- roku_ad_id: (Roku) Roku Advertising Identifier <br>- ad_tracking_enabled: If ad tracking is enabled on the device, can be true or false
dobStringUser's date of birth in the format YYYY-MM-DD.
emailStringUser's email address.
external_idStringUnique user identifier for identified users.
first_nameStringUser's first name.
genderStringUser's gender. Possible values are: <br> <br>- M: male <br>- F: female <br>- O: other <br>- N: not applicable <br>- P: prefer not to say <br>- nil: unknown
home_cityStringUser's home city.
languageStringUser's language in ISO-639-1 standard.
last_coordinatesArray of floatsUser's most recent device location, formatted as [longitude, latitude].
last_nameStringUser's last name.
phoneStringUser's telephone number in E.164 format.
purchasesArrayPurchases this user has made in the last 90 days.
random_bucketIntegerUser's random bucket number, used to create uniformly distributed segments of random users.
time_zoneStringUser's time zone in the same format as the IANA Time Zone Database.
total_revenueFloatTotal 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_atTimestampDate and time the user uninstalls the app. Omitted if the app has not been uninstalled.
user_aliasesObjectUser aliases object containing the alias_name and alias_label, if exists.

important-reminders

Important reminders

  • The fields for custom_events, purchases, campaigns_received, and canvases_received will contain only contain data from the last 90 days.

  • Both custom_events and purchases contain fields for first and count. Both of these fields will reflect information from all time, and will not be limited to just data from the last 90 days. For example, if a particular user first did the event prior to 90 days ago, this will be accurately reflected in the first field, and the count field will take into account events that occurred prior to the last 90 days as well.

  • The number of concurrent segment exports a company can run at the endpoint level is capped at 100. Attempts that surpass this limit will result in an error.

  • Attempting to export a segment a second time while the first export job is still running will result in a 429 error.

response

Response

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "message": (required, string) the status of the export, returns 'success' when completed without errors,
  "object_prefix": (required, string) the filename prefix that will be used for the JSON file produced by this export, e.g. 'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599',
  "url" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials
}

Once made available, the URL will only be valid for a few hours. As such, we highly recommend that you add your own S3 credentials to Braze.

sample-user-export-file-output

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):

{
  "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" : (string),
          "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_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)
      },
      ...
  ]
}

Sample output

{
  "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" : "example@braze.com",
  "dob" : "1980-12-21",
  "home_city" : "Chicago",
  "country" : "US",
  "phone" : "+442071838750",
  "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
    },
    ...
  ],
  "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,
      "last_exited": "2021-07-07T20:46:24.136Z",
      "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.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • opts (keyword): Optional parameters
    • :"Content-Type" (String.t):
    • :Authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure