Exportar perfil de usuário por identificador
/users/export/ids
Use esse endpoint para exportar dados de qualquer perfil de usuário, especificando um identificador de usuário.
Até 50 external_ids
ou user_aliases
podem ser incluídos em uma única solicitação. Se quiser especificar device_id
, email_address
ou phone
, somente um de cada identificador poderá ser incluído por solicitação.
Pré-requisitos
Para usar esse endpoint, você precisará de uma chave de API com a permissão users.export.ids
.
Limite de taxa
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.
Corpo da solicitação
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
}
Parâmetros de solicitação
Parâmetro | Obrigatória | Tipo de dados | Descrição |
---|---|---|---|
external_ids |
Opcional | Matriz de strings | Identificadores externos para os usuários que deseja exportar. |
user_aliases |
Opcional | Vetor de objeto de alias de usuário | Aliases de usuário para usuários a serem exportados. |
device_id |
Opcional | String | Identificador do dispositivo, conforme retornado por vários métodos do SDK, como getDeviceId . |
braze_id |
Opcional | String | Identificador do Braze para um usuário específico. |
email_address |
Opcional | String | Endereço de e-mail do usuário. |
phone |
Opcional | String em E.164 formato | Número de telefone do usuário. |
fields_to_export |
Opcional | Matriz de strings | Nome dos campos de dados de usuários a serem exportados. O padrão é all se não for fornecido. |
Exemplo de solicitação
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"]
}'
Campos a serem exportados
A seguir, uma lista de fields_to_export
válidos. O uso do site fields_to_export
para minimizar os dados retornados pode melhorar o tempo de resposta desse endpoint da API:
Campo a ser exportado | Tipo de dados | Descrição |
---|---|---|
apps |
Vetor | Apps nos quais esse usuário registrou sessões, que incluem os campos: - name : nome do app- platform : plataforma do app, como iOS, Android ou Web- version : número ou nome da versão do app - sessions : número total de sessões para este app- first_used : data da primeira sessão- last_used : data da última sessãoTodos os campos são strings. |
attributed_campaign |
String | Dados de integrações de atribuição, se configurados. Identificador de uma determinada campanha publicitária. |
attributed_source |
String | Dados de integrações de atribuição, se configurados. Identificador da plataforma em que o anúncio estava. |
attributed_adgroup |
String | Dados de integrações de atribuição, se configurados. Identificador de um subgrupo opcional abaixo da campanha. |
attributed_ad |
String | Dados de integrações de atribuição, se configurados. Identificador de um subgrupo opcional abaixo da campanha e do grupo de anúncios. |
braze_id |
String | Identificador de usuário exclusivo específico do dispositivo definido pelo Braze para esse usuário. |
country |
String | País do usuário usando o padrão ISO 3166-1 alfa-2. |
created_at |
String | Data e hora em que o perfil do usuário foi criado, no formato ISO 8601. |
custom_attributes |
Objeto | Pares de valores-chave de atributos personalizados para esse usuário. |
custom_events |
Vetor | Eventos personalizados atribuídos a esse usuário nos últimos 90 dias. |
devices |
Vetor | Informações sobre o dispositivo do usuário, que podem incluir o seguinte, dependendo da plataforma: - model : Nome do modelo do dispositivo- os : Sistema operacional do dispositivo- carrier : Operadora de serviço do dispositivo, se disponível- idfv : (iOS) identificador do dispositivo Braze, o identificador da Apple para o fornecedor, se houver- idfa : (iOS) identificador para publicidade, se houver- device_id : (Android) Identificador do dispositivo Braze- google_ad_id : (Android) Identificador de publicidade do Google Play, se houver- roku_ad_id : (Roku) Identificador de publicidade da Roku- ad_tracking_enabled : Se o rastreamento de anúncios estiver ativado no dispositivo, pode ser verdadeiro ou falso. |
dob |
String | Data de nascimento do usuário no formato YYYY-MM-DD . |
email |
String | Endereço de e-mail do usuário. |
external_id |
String | Identificador de usuário exclusivo para usuários identificados. |
first_name |
String | Nome do usuário. |
gender |
String | Gênero do usuário. Os valores possíveis são: - M : masculino- F : feminino- O : outros- N : não aplicável- P : prefere não se pronunciar- nil : desconhecido |
home_city |
String | Cidade natal do usuário. |
language |
String | Idioma do usuário no padrão ISO-639-1. |
last_coordinates |
Matriz de valores flutuantes | O local mais recente do dispositivo do usuário, formatado como [longitude, latitude] . |
last_name |
String | Sobrenome do usuário. |
phone |
String | Número de telefone do usuário no formato E.164. |
purchases |
Vetor | Compras que esse usuário fez nos últimos 90 dias. |
push_tokens |
Vetor | Identificador anônimo exclusivo que especifica para onde enviar as notificações de um app. |
random_bucket |
Inteiro | Número de bucket aleatório do usuário, usado para criar segmentos uniformemente distribuídos de usuários aleatórios. |
time_zone |
String | Fuso horário do usuário no mesmo formato do banco de dados de fuso horário da IANA. |
total_revenue |
Flutuação | Receita total atribuída a esse usuário. A receita total é calculada com base nas compras que o usuário fez durante as janelas de conversão para as campanhas e Canvas que recebeu. |
uninstalled_at |
Data e hora | Data e hora em que o usuário desinstala o app. Omitido se o app não tiver sido desinstalado. |
user_aliases |
Objeto | Objeto de aliases de usuário contendo alias_name e alias_label , se houver. |
Esteja ciente de que o ponto de extremidade /users/export/ids
reunirá todo o perfil desse usuário, incluindo dados como todas as campanhas e Canvas recebidos, todos os eventos personalizados realizados, todas as compras feitas e todos os atributos personalizados. Como resultado, esse endpoint é mais lento do que outros endpoints da API REST.
Dependendo dos dados solicitados, esse endpoint da API pode não ser suficiente para atender às suas necessidades devido ao limite de frequência de 2.500 solicitações por minuto. Se você pretende usar esse endpoint regularmente para exportar usuários, considere exportar usuários por segmento, que é um processo assíncrono e mais otimizado para extrações de dados maiores.
Resposta
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
}
Para obter um exemplo dos dados que podem ser acessados por meio desse endpoint, veja o exemplo a seguir.
Exemplo de saída de arquivo de exportação do usuário
Objeto de exportação do usuário (incluiremos o mínimo de dados possível - se um campo estiver faltando no objeto, ele deverá ser considerado nulo, falso ou vazio):
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"
},
...
]
}
Para obter ajuda com exportações CSV e API, acesse Solução de problemas de exportação.