識別子によるユーザープロファイルのエクスポート
/users/export/ids
このエンドポイントを使用して、ユーザー識別子を指定して任意のユーザープロファイルからデータをエクスポートします。
1つのリクエストには、最大50個のexternal_idsまたはuser_aliasesを含めることができます。device_id、email_address、またはphoneを指定する場合、リクエストごとにこれらの識別子のうち1つのみを含めることができます。
前提条件
このエンドポイントを使用するには、users.export.ids権限を持つAPIキーが必要です。
レート制限
2024年8月22日以降にBrazeにオンボーディングした場合、このエンドポイントには、APIレート制限に記載されているように、1分あたり250リクエストのレート制限が適用されます。
以下の要件を満たすことで、このエンドポイントのレート制限を1秒あたり40リクエストまで引き上げることもできます。
- ワークスペースにデフォルトのレート制限(1分あたり250リクエスト)が有効になっていること。既存のレート制限の解除についてサポートが必要な場合は、担当のBrazeアカウントマネージャーにお問い合わせください。
- リクエストに、受け取りたいすべてのフィールドを列挙する
fields_to_exportパラメーターが含まれていること。

fields_to_exportパラメーターにcanvases_receivedまたはcampaigns_receivedを含めると、リクエストは高速なレート制限の対象外となります。これらをリクエストに含めるのは、具体的なユースケースがある場合に限ることを推奨します。
リクエスト本文
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
"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
}

2024年8月22日以降にBrazeにオンボーディングした顧客については、リクエストパラメーターfields_to_exportが必須です。
リクエストパラメーター
| パラメーター | 必須 | データタイプ | 説明 |
|---|---|---|---|
external_ids |
オプション | 文字列の配列 | エクスポートするユーザーの外部識別子。 |
user_aliases |
オプション | ユーザーエイリアスオブジェクトの配列 | エクスポートするユーザーのユーザーエイリアス。 |
device_id |
オプション | 文字列 | getDeviceIdなどのさまざまなSDKメソッドによって返されるデバイス識別子。 |
braze_id |
オプション | 文字列 | 特定のユーザーのBraze識別子。 |
email_address |
オプション | 文字列 | ユーザーのメールアドレス。 |
phone |
オプション | E.164形式の文字列 | ユーザーの電話番号。 |
fields_to_export |
オプション* | 文字列の配列 | エクスポートするユーザーデータフィールドの名前。 *このフィールドは、1秒あたり40リクエストの高速レート制限を使用するために必要です。省略した場合、1分あたり250リクエストのデフォルトレート制限が代わりに使用されます。 |
*2024年8月22日以降にBrazeにオンボーディングした顧客には必須です。
リクエスト例
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"]
}'
エクスポートするフィールド
以下は、有効なfields_to_exportのリストです。fields_to_exportを使用して返されるデータを最小限に抑えると、このAPIエンドポイントのレスポンスタイムが向上します。
| エクスポートするフィールド | データタイプ | 説明 |
|---|---|---|
apps |
配列 | このユーザーがセッションを記録したアプリ。以下のフィールドが含まれます。 - name: アプリ名- platform: アプリプラットフォーム(iOS、Android、Webなど)- version: アプリのバージョン番号または名前- sessions: このアプリの総セッション数- first_used: 初回セッションの日付- last_used: 最終セッションの日付すべてのフィールドは文字列です。 |
attributed_campaign |
文字列 | アトリビューション統合からのデータ(設定されている場合)。特定の広告キャンペーンの識別子。 |
attributed_source |
文字列 | アトリビューション統合からのデータ(設定されている場合)。広告が表示されたプラットフォームの識別子。 |
attributed_adgroup |
文字列 | アトリビューション統合からのデータ(設定されている場合)。キャンペーンの下のオプションのサブグループの識別子。 |
attributed_ad |
文字列 | アトリビューション統合からのデータ(設定されている場合)。キャンペーンおよび広告グループの下のオプションのサブグループの識別子。 |
push_subscribe |
文字列 | ユーザーのプッシュ通知の購読ステータス。 |
email_subscribe |
文字列 | ユーザーのメール購読ステータス。 |
braze_id |
文字列 | このユーザーにBrazeが設定したデバイス固有の一意のユーザー識別子。 |
country |
文字列 | ISO 3166-1 alpha-2標準を使用したユーザーの国。 |
created_at |
文字列 | ユーザープロファイルが作成された日時(ISO 8601形式)。 |
custom_attributes |
オブジェクト | このユーザーのカスタム属性のキーと値のペア。 |
custom_events |
配列 | 過去90日間にこのユーザーに帰属するカスタムイベント。 |
devices |
配列 | ユーザーのデバイスに関する情報。プラットフォームに応じて以下が含まれます。 - model: デバイスのモデル名- os: デバイスのオペレーティングシステム- carrier: デバイスのサービスキャリア(利用可能な場合)- idfv: (iOS) Brazeデバイス識別子、Apple Identifier for Vendor(存在する場合)- idfa: (iOS) Identifier for Advertising(存在する場合)- device_id: (Android) Brazeデバイス識別子- google_ad_id: (Android) Google Play Advertising Identifier(存在する場合)- roku_ad_id: (Roku) Roku Advertising Identifier- ad_tracking_enabled: デバイスで広告トラッキングが有効になっている場合、trueまたはfalse |
dob |
文字列 | YYYY-MM-DD形式のユーザーの生年月日。 |
email |
文字列 | ユーザーのメールアドレス。 |
external_id |
文字列 | 識別済みユーザーの一意のユーザー識別子。 |
first_name |
文字列 | ユーザーの名。 |
gender |
文字列 | ユーザーの性別。可能な値は以下のとおりです。 - M: 男性- F: 女性- O: その他- N: 該当なし- P: 回答しない- nil: 不明 |
home_city |
文字列 | ユーザーの居住都市。 |
language |
文字列 | ISO-639-1標準のユーザーの言語。 |
last_coordinates |
浮動小数点の配列 | [longitude, latitude]としてフォーマットされたユーザーの最新のデバイスの位置。 |
last_name |
文字列 | ユーザーの姓。 |
phone |
文字列 | E.164形式のユーザーの電話番号。 |
purchases |
配列 | このユーザーが過去90日間に行った購入。 |
push_tokens |
配列 | アプリの通知の送信先を指定する一意の匿名識別子。 |
random_bucket |
整数 | ユーザーの乱数バケット番号。ランダムユーザーの均一分布セグメントを作成するために使用されます。 |
time_zone |
文字列 | IANAタイムゾーンデータベースと同じ形式のユーザーのタイムゾーン。 |
total_revenue |
浮動小数点 | このユーザーに帰属する総収益。総収益は、受信したキャンペーンおよびキャンバスのコンバージョン期間中にユーザーが行った購入に基づいて計算されます。 |
uninstalled_at |
タイムスタンプ | ユーザーがアプリをアンインストールした日時。アプリがアンインストールされていない場合は省略されます。 |
user_aliases |
オブジェクト | alias_nameおよびalias_labelを含むユーザーエイリアスオブジェクト(存在する場合)。 |
/users/export/idsエンドポイントは、受信したすべてのキャンペーンやキャンバス、実行されたすべてのカスタムイベント、行われたすべての購入、すべてのカスタム属性などのデータを含む、このユーザーのユーザープロファイル全体をまとめることに注意してください。このため、このエンドポイントは他のREST APIエンドポイントよりも低速になります。
リクエストされたデータによっては、このAPIエンドポイントでは1分あたり250件のリクエストのレート制限があるため、ニーズを満たすには不十分な場合があります。このエンドポイントを定期的に使用してユーザーをエクスポートすることを想定している場合は、代わりに、非同期で大規模なデータプルに最適化されているセグメント別のユーザーエクスポートを検討してください。
レスポンス
{
"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
}
このエンドポイントからアクセスできるデータの例については、以下の例を参照してください。
ユーザーエクスポートファイルの出力例
ユーザーエクスポートオブジェクト(できるだけ少ないデータを含めます。オブジェクトにフィールドがない場合は、nullまたは空であると見なされます):
{
"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),
"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)
},
...
]
}
{
"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,
"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"
},
...
]
}
