Exporter le profil utilisateur par identifiant
/users/export/ids
Utilisez cet endpoint pour exporter des données à partir de n’importe quel profil utilisateur en spécifiant un identifiant utilisateur.
Vous pouvez inclure jusqu’à 50 external_ids ou user_aliases dans une seule requête. Si vous souhaitez spécifier device_id, email_address ou phone, un seul de ces identifiants peut être inclus par requête.
Conditions préalables
Pour utiliser cet endpoint, vous aurez besoin d’une clé API avec l’autorisation users.export.ids.
Limite de débit
Si vous avez réalisé l’onboarding avec Braze le 22 août 2024 ou après, cet endpoint présente une limite de débit de 250 requêtes par minute, comme documenté dans Limites de débit de l’API.
Vous pouvez également augmenter la limite de débit de cet endpoint à 40 requêtes par seconde en respectant les conditions suivantes :
- Votre espace de travail dispose de la limite de débit par défaut (250 requêtes par minute) activée. Contactez votre gestionnaire de compte Braze pour obtenir de l’aide afin de supprimer toute limite de débit préexistante dont vous pourriez disposer.
- Votre requête inclut le paramètre
fields_to_exportpour lister tous les champs que vous souhaitez recevoir.

Si vous incluez canvases_received ou campaigns_received dans le paramètre fields_to_export, votre requête ne sera pas éligible à la limite de débit plus élevée. Nous vous recommandons de ne les inclure dans votre requête que si vous avez un cas d’utilisation spécifique.
Corps de la requête
1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
4
5
6
7
8
9
{
"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
}

Pour les clients ayant intégré Braze le 22 août 2024 ou après, le paramètre de requête fields_to_export est requis.
Paramètres de requête
| Paramètre | Requis | Type de données | Description |
|---|---|---|---|
external_ids |
Facultatif | Tableau de chaînes de caractères | Identifiants externes des utilisateurs que vous souhaitez exporter. |
user_aliases |
Facultatif | Tableau d’objets alias d’utilisateur | Alias d’utilisateur pour les utilisateurs à exporter. |
device_id |
Facultatif | Chaîne de caractères | Identifiant d’appareil, tel que renvoyé par diverses méthodes SDK comme getDeviceId. |
braze_id |
Facultatif | Chaîne de caractères | Identifiant Braze d’un utilisateur particulier. |
email_address |
Facultatif | Chaîne de caractères | Adresse e-mail de l’utilisateur. |
phone |
Facultatif | Chaîne de caractères au format E.164 | Numéro de téléphone de l’utilisateur. |
fields_to_export |
Facultatif* | Tableau de chaînes de caractères | Nom des champs de données utilisateur à exporter. *Ce champ est requis pour bénéficier de la limite de débit plus rapide de 40 requêtes par seconde. S’il est omis, la limite de débit par défaut de 250 requêtes par minute sera utilisée à la place. |
*Requis pour les clients ayant intégré Braze le 22 août 2024 ou après.
Exemple de requête
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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": "[email protected]",
"phone": "11112223333",
"fields_to_export": ["first_name", "email", "purchases"]
}'
Champs à exporter
Voici une liste des valeurs valides pour fields_to_export. Utiliser fields_to_export pour minimiser les données renvoyées peut améliorer le temps de réponse de cet endpoint d’API :
| Champ à exporter | Type de données | Description |
|---|---|---|
apps |
Tableau | Applications pour lesquelles l’utilisateur a enregistré des sessions, comprenant les champs : - name : nom de l’application- platform : plateforme de l’application, telle qu’iOS, Android ou Web- version : numéro ou nom de version de l’application- sessions : nombre total de sessions pour cette application- first_used : date de la première session- last_used : date de la dernière sessionTous les champs sont des chaînes de caractères. |
attributed_campaign |
Chaîne de caractères | Données provenant des intégrations d’attribution, si elles sont configurées. Identifiant d’une campagne publicitaire donnée. |
attributed_source |
Chaîne de caractères | Données provenant des intégrations d’attribution, si elles sont configurées. Identifiant de la plateforme sur laquelle se trouvait l’annonce. |
attributed_adgroup |
Chaîne de caractères | Données provenant des intégrations d’attribution, si elles sont configurées. Identifiant d’un sous-groupe facultatif en dessous de la campagne. |
attributed_ad |
Chaîne de caractères | Données provenant des intégrations d’attribution, si elles sont configurées. Identifiant d’un sous-groupe facultatif en dessous de la campagne et du groupe d’annonces. |
push_subscribe |
Chaîne de caractères | Statut d’abonnement push de l’utilisateur. |
email_subscribe |
Chaîne de caractères | Statut d’abonnement e-mail de l’utilisateur. |
braze_id |
Chaîne de caractères | Identifiant utilisateur unique spécifique à l’appareil, défini par Braze pour cet utilisateur. |
country |
Chaîne de caractères | Pays de l’utilisateur selon la norme ISO 3166-1 alpha-2. |
created_at |
Chaîne de caractères | Date et heure de création du profil utilisateur, au format ISO 8601. |
custom_attributes |
Objet | Paires clé-valeur des attributs personnalisés de cet utilisateur. |
custom_events |
Tableau | Événements personnalisés attribués à cet utilisateur au cours des 90 derniers jours. |
devices |
Tableau | Informations sur l’appareil de l’utilisateur, pouvant inclure les éléments suivants selon la plateforme : - model : nom du modèle de l’appareil- os : système d’exploitation de l’appareil- carrier : opérateur de l’appareil, si disponible- idfv : (iOS) identifiant d’appareil Braze, l’identifiant Apple pour le fournisseur, s’il existe- idfa : (iOS) identifiant publicitaire, s’il existe- device_id : (Android) identifiant d’appareil Braze- google_ad_id : (Android) identifiant publicitaire Google Play, s’il existe- roku_ad_id : (Roku) identifiant publicitaire Roku- ad_tracking_enabled : indique si le suivi publicitaire est activé sur l’appareil, peut être vrai ou faux |
dob |
Chaîne de caractères | Date de naissance de l’utilisateur au format YYYY-MM-DD. |
email |
Chaîne de caractères | Adresse e-mail de l’utilisateur. |
external_id |
Chaîne de caractères | Identifiant utilisateur unique pour les utilisateurs identifiés. |
first_name |
Chaîne de caractères | Prénom de l’utilisateur. |
gender |
Chaîne de caractères | Genre de l’utilisateur. Les valeurs possibles sont : - M : masculin- F : féminin- O : autre- N : sans objet- P : préfère ne pas répondre- nil : inconnu |
home_city |
Chaîne de caractères | Ville de résidence de l’utilisateur. |
language |
Chaîne de caractères | Langue de l’utilisateur selon la norme ISO-639-1. |
last_coordinates |
Tableau de floats | Dernier emplacement connu de l’appareil de l’utilisateur, au format [longitude, latitude]. |
last_name |
Chaîne de caractères | Nom de famille de l’utilisateur. |
phone |
Chaîne de caractères | Numéro de téléphone de l’utilisateur au format E.164. |
purchases |
Tableau | Achats effectués par cet utilisateur au cours des 90 derniers jours. |
push_tokens |
Tableau | Identifiant anonyme unique qui spécifie où envoyer les notifications d’une application. |
random_bucket |
Entier | Numéro de compartiment aléatoire de l’utilisateur, utilisé pour créer des segments uniformément distribués d’utilisateurs aléatoires. |
time_zone |
Chaîne de caractères | Fuseau horaire de l’utilisateur, au même format que la base de données de fuseaux horaires IANA. |
total_revenue |
Float | Chiffre d’affaires total attribué à cet utilisateur. Le chiffre d’affaires total est calculé à partir des achats effectués par l’utilisateur pendant les fenêtres de conversion des Campaigns et Canvas qu’il a reçus. |
uninstalled_at |
Horodatage | Date et heure de désinstallation de l’application par l’utilisateur. Absent si l’application n’a pas été désinstallée. |
user_aliases |
Objet | Objet alias d’utilisateur contenant les champs alias_name et alias_label, s’ils existent. |
Sachez que l’endpoint /users/export/ids récupère l’intégralité du profil utilisateur, y compris les données telles que toutes les Campaigns et Canvas reçus, tous les événements personnalisés effectués, tous les achats réalisés et tous les attributs personnalisés. Par conséquent, cet endpoint est plus lent que les autres endpoints de la REST API.
En fonction des données demandées, cet endpoint d’API peut ne pas suffire à répondre à vos besoins en raison de la limite de débit de 250 requêtes par minute. Si vous prévoyez d’utiliser cet endpoint régulièrement pour exporter des utilisateurs, envisagez plutôt d’exporter les utilisateurs par segment, ce qui est asynchrone et mieux optimisé pour les extractions de données volumineuses.
Réponse
1
2
3
4
5
{
"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
}
L’exemple suivant illustre les données accessibles via cet endpoint.
Exemple de sortie d’un fichier d’exportation utilisateur
Objet d’exportation utilisateur (nous inclurons le minimum de données possible — si un champ est absent de l’objet, il doit être considéré comme nul ou vide) :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
{
"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
},
...
],
"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)
},
...
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
{
"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" : "[email protected]",
"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"
},
...
]
}

Pour obtenir de l’aide sur les exportations CSV et API, consultez la section Résolution des problèmes d’exportation.