Skip to content

Exporter le profil utilisateur par identifiant

post

/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 un device_id, une email_address ou un 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

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.

Corps de la demande

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. Defaults to all if not provided
}

Paramètres de demande

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 utilisateur Alias de l’ utilisateur pour les utilisateurs à exporter.
device_id Facultatif Chaîne de caractères L’identifiant d’appareil, tel que renvoyé par diverses méthodes SDK, telles que 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 dans E.164 format 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. Par défaut sur Tous, si non renseigné.

Exemple de demande

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": "example@braze.com",
  "phone": "11112223333",
  "fields_to_export": ["first_name", "email", "purchases"]
}'

Champs à exporter

Voici une liste des fields_to_export valides. 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 Les applications pour lesquelles l’utilisateur a enregistré des sessions, ce qui comprend 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 session

Tous 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 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 était l’annonce.
attributed_adgroup Chaîne de caractères Données provenant des intégrations d’attribution, si elles sont configurées. Identifiant pour un sous-groupe optionnel sous 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-groupement facultatif en dessous de la campagne et du groupe d’annonces.
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 la création du profil utilisateur au format ISO 8601.
custom_attributes Objet Paires clé-valeur de l’attribut personnalisé de cet utilisateur.
custom_events Tableau Événements personnalisés attribués à cet utilisateur dans les 90 derniers jours.
devices Tableau Informations sur l’appareil de l’utilisateur qui devraient contenir les éléments suivants selon la plateforme :

- model : Nom du modèle de l’appareil
- os : Système d’exploitation de l’appareil
- carrier : Fournisseur de services de l’appareil, si disponible
- idfv: (iOS) Identifiant de l’appareil Braze, l’identifiant Apple pour le vendeur, s’il existe.
- idfa : (iOS) Identifiant publicitaire, s’il existe
- device_id : (Android) Identifiant de l’appareil Braze
- google_ad_id : (Android) Identifiant publicitaire Google Play, s’il existe
- roku_ad_id : (Roku) Identifiant publicitaire Roku
- ad_tracking_enabled : Si le suivi des annonces 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 à la norme ISO-639-1.
last_coordinates Tableau de floats Dernier emplacement 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 réalisé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 app.
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 Revenus totaux attribués à cet utilisateur. Les revenus totaux sont calculés à partir des achats réalisés par l’utilisateur pendant la fenêtre de conversion pour les campagnes et les Canvas qu’il a reçus.
uninstalled_at Date/heure 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 aliasing de l’utilisateur contenant les adresses alias_name et alias_label, si elles existent.

Sachez que l’endpoint /users/export/ids extraira l’intégralité du profil utilisateur de cet utilisateur, y compris les données telles que toutes les campagnes et les Canvas reçus, tous les événements personnalisés et tous les achats effectués, et tous les attributs personnalisés. Par conséquent, cet endpoint est plus lent que les autres endpoints d’API REST.

Selon les données demandées, cet endpoint d’API peut ne pas être suffisant pour répondre à vos besoins en raison de la limite de débit à 2 500 demandes par minute. Si vous prévoyez d’utiliser cet endpoint régulièrement pour exporter des utilisateurs, envisagez plutôt de le faire par segment, ce qui est asynchrone et plus optimisé pour les extractions de données plus importantes.

Réponse

1
2
3
4
5
6
7
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
}

L’exemple suivant illustre les données accessibles via cet endpoint.

Exemple de sortie d’un fichier d’exportation utilisateur

Objet Exportation utilisateur (nous inclurons le moins de données possible. S’il manque un champ de l’objet, il doit être considéré comme nul, faux 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
{
    "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)
      },
      ...
    ]
}
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" : "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"
      },
      ...
    ]
}
CETTE PAGE A-T-ELLE ÉTÉ UTILE?
New Stuff!