Skip to content

Exportar perfil de usuário por identificador

post

/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 você quiser especificar device_id, email_address ou phone, somente um desses identificadores 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

Se sua integração com a Braze ocorreu em 22 de agosto de 2024 ou após essa data, esse endpoint tem um limite de taxa de 250 solicitações por minuto, conforme documentado em Limites de taxa da API.

Você também pode aumentar o limite de taxa desse endpoint para 40 solicitações por segundo atendendo aos seguintes requisitos:

  • Seu espaço de trabalho tem o limite de taxa padrão (250 solicitações por minuto) ativado. Entre em contato com seu gerente de conta da Braze para mais assistência na remoção de qualquer limite de taxa pré-existente que você possa ter.
  • Sua solicitação inclui o parâmetro fields_to_export para listar todos os campos que você deseja receber.

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
}

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 Matriz de objetos 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 da Braze para um usuário específico.
email_address Opcional String Endereço de e-mail do usuário.
phone Opcional String no formato E.164 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.

*Este campo é obrigatório para usar o limite de taxa mais rápido de 40 solicitações por segundo. Se omitido, será usado o limite de taxa padrão de 250 solicitações por minuto.

*Obrigatório para clientes que fizeram a integração com a Braze em 22 de agosto de 2024 ou após essa data.

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": "[email protected]",
  "phone": "11112223333",
  "fields_to_export": ["first_name", "email", "purchases"]
}'

Campos a serem exportados

A seguir, uma lista de fields_to_export válidos. Usar 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 Matriz 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ão

Todos 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.
push_subscribe String Status da inscrição push do usuário.
email_subscribe String Status da inscrição de e-mail do usuário.
braze_id String Identificador de usuário exclusivo específico do dispositivo definido pela 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 chave-valor de atributos personalizados para esse usuário.
custom_events Matriz Eventos personalizados atribuídos a esse usuário nos últimos 90 dias.
devices Matriz 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 Apple Identifier for Vendor, se houver
- idfa: (iOS) Identifier for Advertising, se houver
- device_id: (Android) identificador do dispositivo Braze
- google_ad_id: (Android) Google Play Advertising Identifier, se houver
- roku_ad_id: (Roku) Roku Advertising Identifier
- ad_tracking_enabled: se o rastreamento de anúncios estiver ativado no dispositivo, pode ser true ou false
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 dizer
- 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 floats Localização mais recente do dispositivo do usuário, formatada como [longitude, latitude].
last_name String Sobrenome do usuário.
phone String Número de telefone do usuário no formato E.164.
purchases Matriz Compras que esse usuário fez nos últimos 90 dias.
push_tokens Matriz 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 Float 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 das Campaigns e Canvas que recebeu.
uninstalled_at Timestamp 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 endpoint /users/export/ids reunirá todo o perfil desse usuário, incluindo dados como todas as Campaigns 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 REST API.

Dependendo dos dados solicitados, esse endpoint da API pode não ser suficiente para atender às suas necessidades devido ao limite de taxa de 250 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
{
    "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 ver um exemplo dos dados acessíveis por meio desse endpoint, consulte 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 ausente no objeto, ele deve ser considerado nulo 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
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"
      },
      ...
    ]
}
New Stuff!