Criar ou substituir relacionamentos de usuários em massa
/data_objects/user_relationships
Use este endpoint para criar ou substituir até 50 relacionamentos entre usuários e objetos em uma única solicitação.

Os Data Objects estão disponíveis para todos, mas seu espaço de trabalho precisa estar provisionado para Contas antes que você possa usar este endpoint. Para solicitar o provisionamento, acesse Configurações de dados > Contas e preencha o questionário. Para saber mais, consulte Ativar Contas.
A Braze aceita a solicitação e a processa em segundo plano. Uma resposta 202 significa que o lote está na fila, não que foi aplicado. Para alterar um único relacionamento e ver a mudança na hora, use Substituir relacionamento de usuário. Para saber quando usar cada um, consulte Endpoints em massa.
Pré-requisitos
Para usar este endpoint, você precisará de uma chave de API com a permissão data_objects.user_relationships.bulk_upsert. As permissões de registro único, como data_objects.user_relationships.create, não concedem acesso a este endpoint.
Limite de frequência
Este endpoint faz parte do bucket de gravação em massa de Data Objects, com um limite padrão de 1.000 solicitações por minuto por espaço de trabalho. O limite é compartilhado entre os seis endpoints em massa e com as sincronizações de data objects do Cloud Data Ingestion. Ele é separado do limite de gravação de registro único.
Parâmetros de solicitação
A tabela a seguir lista e descreve os parâmetros do corpo da solicitação JSON para o endpoint /data_objects/user_relationships.
| Parâmetro | Obrigatória | Tipo de dados | Descrição |
|---|---|---|---|
records |
Obrigatória | Array | Os relacionamentos de usuários a serem criados ou substituídos. Deve conter de 1 a 50 registros. A Braze rejeita qualquer outro campo de nível superior. |
records[].type_name |
Obrigatória | String | Tipo do objeto ao qual o usuário está vinculado |
records[].object_id |
Obrigatória | String | Identificador do objeto ao qual o usuário está vinculado |
records[].rel_kind |
Obrigatória | String | Nome do tipo de relacionamento. Para listar os valores válidos, use Listar tipos de relacionamento de usuário. |
records[].user |
Obrigatória | Objeto | O usuário a ser vinculado. Deve conter exatamente um destes: external_id, braze_id, email, phone ou alias. Enviar nenhum ou mais de um gera um erro. |
records[].user.external_id |
Opcional | String | O ID externo do usuário |
records[].user.braze_id |
Opcional | String | O ID de usuário da Braze |
records[].user.email |
Opcional | String | O endereço de e-mail do usuário |
records[].user.phone |
Opcional | String | O número de telefone do usuário |
records[].user.alias |
Opcional | Objeto | Objeto de alias de usuário com alias_name e alias_label (ambos obrigatórios quando usado) |
records[].attributes |
Obrigatória | Objeto | Atributos do relacionamento, indexados pelo nome do campo. Envie {} se o tipo de relacionamento não tiver atributos. |
Quando um endereço de e-mail ou número de telefone corresponde a mais de um usuário, as regras padrão de seleção de perfil da Braze decidem qual usuário será vinculado.
Como a Braze processa o lote
- A validação é tudo ou nada. Se algum registro falhar na validação, a Braze rejeita a solicitação inteira com
400, não armazena nada e lista todos os erros. Corrija os erros e reenvie a solicitação completa. - As consultas acontecem durante o processamento. Ao processar o lote, a Braze verifica se o tipo, o tipo de relacionamento, o objeto e o usuário existem, e se os atributos correspondem aos campos do tipo de relacionamento. Uma solicitação que retorna
202ainda pode gerar falhas em registros individuais mais tarde. Consulte Falhas de processamento. - Os registros são ordenados pelo horário de recebimento. A Braze marca cada registro com o horário em que recebeu a solicitação, então não envie
updated_at. A Braze rejeita qualquer solicitação que inclua esse campo. Quando duas solicitações alteram o mesmo relacionamento, prevalece a que a Braze recebeu por último, e a Braze ignora uma gravação mais antiga que chegue depois. - Os relacionamentos podem aguardar seu objeto e usuário. Um relacionamento cujo objeto ou usuário ainda não existe fica aguardando em vez de falhar imediatamente. A Braze tenta novamente por cerca de 40 horas (10 tentativas). Se o objeto ou usuário ainda não existir depois disso, o registro falha com
data-object-dependency-not-found.
Exemplo de solicitação
Esta seção inclui um exemplo de carga útil JSON e um exemplo de solicitação cURL.
Exemplo de carga útil da solicitação
{
"records": [
{
"type_name": "account",
"object_id": "acct-001",
"rel_kind": "owns",
"user": {"external_id": "user-1"},
"attributes": {"role": "admin"}
}
]
}
Exemplo de solicitação cURL
Este exemplo vincula o usuário com ID externo user-1 a acct-001 usando o tipo de relacionamento owns e registra o role dele como admin.
curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/user_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"records": [
{
"type_name": "account",
"object_id": "acct-001",
"rel_kind": "owns",
"user": {"external_id": "user-1"},
"attributes": {"role": "admin"}
}
]
}'
Resposta
Esta seção inclui um exemplo de resposta bem-sucedida e os campos da resposta.
Exemplo de resposta bem-sucedida
O código de status 202 pode retornar o seguinte corpo de resposta.
{
"source_import_id": "api-20261022T153012123456-9f3a1c2b",
"status": "queued",
"record_count": 1
}
Parâmetros de resposta
A tabela a seguir lista e descreve os campos de uma resposta bem-sucedida.
| Parâmetro | Obrigatória | Tipo de dados | Descrição |
|---|---|---|---|
source_import_id |
Obrigatória | String | O identificador que a Braze gerou para esta solicitação. Cada solicitação é uma importação própria. |
status |
Obrigatória | String | Sempre queued. O lote foi aceito e está aguardando processamento. |
record_count |
Obrigatória | Inteiro | O número de registros na solicitação |
Falhas de processamento
A Braze não retorna esses códigos pelo endpoint. Ela os registra para registros individuais ao processar um lote na fila.
| Código | Significado |
|---|---|
data-object-type-not-found |
type_name não corresponde a nenhum tipo ativo no espaço de trabalho. |
data-object-relationship-type-not-found |
rel_kind não corresponde a nenhum tipo de relacionamento ativo para este tipo. |
data-object-schema-mismatch |
attributes não corresponde aos campos do tipo de relacionamento. A mensagem indica todos os atributos com problema. |
data-object-invalid-user-identifier |
O identificador de usuário não pode ser usado para encontrar um usuário. |
data-object-ingestion-rejected |
Qualquer outra rejeição. |
data-object-dependency-not-found |
O objeto ou usuário continuava ausente após cerca de 40 horas de novas tentativas. |
Erros
Uma resposta 400 significa que a Braze não armazenou nada. Cada erro tem um id, uma message, o parameter com problema (quando houver) e, para erros no nível do registro, o index do registro (sua posição, começando em 0, em records). O parameter usa os nomes da sua solicitação, como user.external_id.
{
"errors": [
{"index": 0, "id": "schema-mismatch", "parameter": "rel_kind", "message": "rel_kind is required"}
]
}
A tabela a seguir lista os erros comuns deste endpoint e como resolvê-los.
| Status | Causa | Orientação |
|---|---|---|
400 |
Solicitação inválida (invalid-request): o corpo não é um objeto JSON ou é um JSON malformado, records está ausente ou tem menos de 1 ou mais de 50 entradas, ou o corpo contém um campo definido pela Braze (source_type, source_import_id, source_chunk_id ou record_type) |
Envie um objeto JSON cujo único campo seja records, com 1 a 50 registros. |
400 |
Incompatibilidade de esquema (schema-mismatch): um registro não tem um campo obrigatório, tem um campo não reconhecido (incluindo updated_at), tem um campo do tipo errado ou uma string vazia, ou tem um objeto user com mais de um identificador |
Corrija todos os registros listados e reenvie a solicitação completa. |
400 |
Identificador de usuário ausente (missing-user-identifier): o user de um registro não tem identificador |
Envie exatamente um identificador no user de cada registro. |
401 |
Chave da API REST ausente ou inválida | Verifique se o cabeçalho Authorization usa Bearer YOUR_REST_API_KEY e se a chave está ativa. |
403 |
A chave de API não tem permissão ou a solicitação foi bloqueada pela lista de permissões | Confirme se a chave tem data_objects.user_relationships.bulk_upsert e se o seu IP de origem está na lista de permissões da chave, caso configurada. |
404 |
Os Data Objects não estão ativados para sua empresa | Confirme se o seu espaço de trabalho está provisionado para Contas. |
429 |
Limite de frequência excedido | Tente novamente após X-RateLimit-Reset e reduza a frequência das solicitações. |
500 |
Não foi possível aceitar o lote (internal-error) |
A Braze não aceitou nada, então é seguro tentar a solicitação novamente. |