Endpoints de objetos de dados
Use esses endpoints para listar tipos de objetos de dados, gerenciar registros de objetos de dados e gerenciar relacionamentos entre objetos e usuários.

O recurso Objetos de dados está disponível para todos, mas seu espaço de trabalho precisa estar provisionado para Contas antes que você possa usar esses endpoints. Para solicitar o provisionamento, acesse Configurações de dados > Contas e preencha o questionário. Depois que o provisionamento for concluído, as permissões de chave de API de Objetos de dados aparecem em Configurações > Chaves de API. Para mais detalhes, consulte Ativar Contas.
Endpoints de tipo
Endpoints de objeto
Endpoints de relacionamento entre objetos
Endpoints de relacionamento de usuário
URL base e autenticação
Use o endpoint REST do seu espaço de trabalho e envie Authorization: Bearer YOUR_REST_API_KEY. Esta seção explica onde os endpoints de Data Objects estão hospedados e como as solicitações são autenticadas.
- Para os hosts dos endpoints, consulte a visão geral da API da Braze.
- Todas as cargas úteis de solicitação e resposta estão em JSON.
- As solicitações ficam restritas ao espaço de trabalho dono da chave de API.
- Se a chave tiver uma lista de IPs permitidos, endereços IP fora dessa lista retornam
403.
Permissões da chave de API
Esta seção mapeia cada endpoint para a permissão necessária, para que você possa definir o escopo das chaves de API com segurança.
| Permissão | Grupo de endpoints |
|---|---|
data_objects.read |
Leituras de tipos e objetos, e leituras de relacionamentos entre objetos |
data_objects.create |
Criação de objetos |
data_objects.update |
Substituição e atualização de objetos |
data_objects.delete |
Exclusão de objetos |
data_objects.user_relationships.read |
Leituras de relacionamentos com usuários |
data_objects.user_relationships.create |
Criação de relacionamentos com usuários |
data_objects.user_relationships.update |
Substituição e atualização de relacionamentos com usuários |
data_objects.user_relationships.delete |
Exclusão de relacionamentos com usuários |
data_objects.object_relationships.create |
Criação de relacionamentos entre objetos |
data_objects.object_relationships.update |
Substituição e atualização de relacionamentos entre objetos |
data_objects.object_relationships.delete |
Exclusão de relacionamentos entre objetos |
data_objects.bulk_upsert |
Criação ou substituição de objetos em massa |
data_objects.bulk_delete |
Exclusão de objetos em massa |
data_objects.object_relationships.bulk_upsert |
Criação ou substituição de relacionamentos entre objetos em massa |
data_objects.object_relationships.bulk_delete |
Exclusão de relacionamentos entre objetos em massa |
data_objects.user_relationships.bulk_upsert |
Criação ou substituição de relacionamentos com usuários em massa |
data_objects.user_relationships.bulk_delete |
Exclusão de relacionamentos com usuários em massa |

As leituras de relacionamentos entre objetos usam data_objects.read. Não existe uma permissão data_objects.object_relationships.read.
Os endpoints em massa usam permissões próprias, e upsert e exclusão são permissões separadas. As permissões de registro único, como data_objects.create, não concedem acesso aos endpoints em massa.
Limites de frequência
Esta seção explica as cotas de solicitação padrão e os cabeçalhos de resposta para tráfego de leitura e de gravação.
| Bucket | Limite padrão |
|---|---|
| Leituras de Objetos de dados | 1000 solicitações por minuto |
| Gravações de Objetos de dados | 1000 solicitações por minuto |
| Gravações em massa de Objetos de dados | 1000 solicitações por minuto, compartilhadas entre os seis endpoints em massa e com as sincronizações de objetos de dados da Cloud Data Ingestion |
O limite de gravação em massa se aplica por espaço de trabalho e é separado do limite de gravação de registro único.
Toda resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
Para solicitações limitadas, a Braze retorna 429 e uma carga útil de erro com id e message.
{
"errors": [
{
"id": "rate-limit-exceeded",
"message": "You have exceeded your limit of 1000 requests per minute."
}
]
}
Limites do produto
Esta seção lista os limites que a Braze aplica aos Data Objects e o que esperar quando você atinge um deles. Para saber como esses limites se aplicam aos registros de conta, consulte Limites de objetos de conta.
Limites de quantidade
Esses limites se aplicam à sua empresa como um todo, a menos que indicado de outra forma. Eles são capacidades iniciais. Se você precisar de mais registros ou de um limite maior, entre em contato com a equipe da sua conta Braze para solicitar um aumento.
| Limite | Valor padrão |
|---|---|
| Registros de objetos de dados por empresa (em todos os espaços de trabalho) | 50.000 |
| Campos por tipo de objeto de dados | 500 |
| Objetos de dados vinculados a um usuário | 1.000 |
| Usuários vinculados a um objeto de dados | 10.000 |
| Relacionamentos entre objetos para um objeto de dados | 1.000 |
Limites de campos e valores
Esses limites são fixos para todas as empresas.
| Limite | Valor |
|---|---|
| Campos por tipo de relacionamento (relacionamentos de usuário e relacionamentos entre objetos) | 25. Os campos de relacionamento não contam para o limite de campos por tipo de objeto de dados. |
| Tamanho do valor do atributo | 255 caracteres |
| Campos de data | Strings de data e hora no formato RFC 3339 que incluem hora e fuso horário, como 2026-11-03T00:00:00Z. A Braze rejeita valores só com data, como 2026-11-03. Para mais detalhes, consulte Formato do campo de data. |
Tamanho e formato do object_id |
250 caracteres. Apenas letras, números, hifens e sublinhados. |
| Tamanho e formato do nome do campo | 250 caracteres. Apenas letras, números e sublinhados, e não pode começar com sublinhado. |
| Nomes de campo reservados | id, external_id, object_id e display_name não podem ser usados como nomes de campos personalizados. |
Formato do campo de data
Os campos de data aceitam apenas strings de data e hora no formato RFC 3339 que incluam hora e fuso horário. A Braze exige o valor completo para nunca precisar adivinhar uma hora ou um fuso horário. Se a sua fonte armazena valores só com data, como datas de renovação ou de contrato no seu data warehouse, converta esses valores antes de enviá-los. Por exemplo, faça isso na transformação do seu data warehouse.
| Valor | Resultado |
|---|---|
2026-11-03T00:00:00Z |
Aceito |
2026-11-03T00:00:00-05:00 |
Aceito |
2026-11-03 |
Rejeitado porque não tem hora nem fuso horário |
2026-11-03T00:00:00 |
Rejeitado porque não tem fuso horário |
Esse formato se aplica aos campos de data em objetos de dados, relacionamentos de usuário e relacionamentos entre objetos. A forma como a Braze informa um valor rejeitado depende de como você o envia:
- Os endpoints de registro único para criar, substituir e atualizar retornam
400. Se mais de um atributo for inválido, o erro cita apenas o primeiro. - Os endpoints de upsert em massa aceitam a solicitação com
202e depois registram uma falha de processamentodata-object-schema-mismatchpara o registro, comoattributes: renewal_date is not valid for its field. - As sincronizações da ingestão de dados na nuvem usam o mesmo processamento dos endpoints em massa. Então, a Braze não aplica uma linha com valor só de data, e a falha aparece nos logs de sincronização.
Por exemplo, uma solicitação de registro único que envia 2026-11-03 para um campo de data renewal_date retorna esta resposta 400:
{
"error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}
O que acontece quando você atinge um limite
Uma solicitação que excederia um limite de quantidade retorna 422 com um id de erro que identifica o limite:
{
"errors": [
{
"id": "data-object-record-limit-exceeded",
"message": "This company has reached its data object record limit"
}
]
}
| Limite | id do erro |
|---|---|
| Registros de objetos de dados por empresa | data-object-record-limit-exceeded |
| Campos por tipo de objeto de dados | data-object-field-limit-exceeded |
| Campos por tipo de relacionamento | data-object-field-limit-exceeded |
| Objetos de dados vinculados a um usuário | data-objects-per-user-limit-exceeded |
| Usuários vinculados a um objeto de dados | users-per-data-object-limit-exceeded |
| Relacionamentos entre objetos para um objeto de dados | data-object-relationship-limit-exceeded |
Seus registros e relacionamentos existentes continuam no lugar. Somente a solicitação que excederia o limite é rejeitada. Para liberar espaço dentro de um limite, exclua os registros de que você não precisa mais ou remova os relacionamentos que não usa mais. Para aumentar um limite de quantidade, entre em contato com a equipe da sua conta Braze.
Solicitações que falham na validação, como um object_id ou um valor de atributo longo demais, retornam 400. Solicitações acima do limite de frequência retornam 429.
Conceitos principais
Esta seção define os principais identificadores usados em todos os endpoints de Data Objects.
type_name: O nome de máquina do tipo de objeto de dados, exclusivo dentro de um espaço de trabalho.object_id: O identificador do seu objeto, exclusivo dentro de um tipo.user: O usuário em uma solicitação de gravação de relacionamento de usuário, identificado por exatamente um destes campos:external_id,braze_id,alias,emailouphone.attributes: Dados do objeto ou do relacionamento, indexados pelo nome do campo e validados de acordo com o esquema configurado.
Como os relacionamentos funcionam
Esta seção explica os tipos de relacionamento, as arestas de relacionamento e o comportamento do anchor antes de você usar as páginas de referência dos endpoints.
Visão geral do modelo de relacionamento
Use este diagrama para entender como tipos, registros e relacionamentos se encaixam e o que você pode fazer na Braze ao vinculá-los. Você define os tipos no dashboard e grava os registros e os vínculos entre eles por meio destes endpoints.
%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
subgraph define["Set up in the dashboard"]
objtype["Data object types define<br/>the fields a record has"]
reltype["Relationship types determine<br/>which links are allowed"]
end
subgraph write["Write with the API"]
person["A person you<br/>send messages to"]
record["A business record<br/>they belong to"]
related["Another record<br/>connected to it"]
person -- "A user relationship links<br/>a person to a record" --> record
record -- "An object relationship links<br/>one record to another" --> related
end
subgraph unlock["What it unlocks"]
segment["Segment people by the<br/>records they belong to"]
liquid["Personalize messages with<br/>data from those records"]
end
define -- "decides what you<br/>are allowed to link" --> write
write -- "makes these<br/>possible" --> unlock
Tipos e arestas são separados
- Os tipos de relacionamento definem quais vínculos são válidos e são gerenciados no dashboard.
- As arestas de relacionamento são os vínculos reais entre registros. Elas são criadas, atualizadas e excluídas por meio destes endpoints da API.
- Antes de gravar relacionamentos, liste os valores válidos de
rel_kindcom:GET /data_objects/types/{type_name}/user_relationship_typesGET /data_objects/types/{type_name}/object_relationship_types
Por que relacionamentos entre objetos exigem related_type_name
- O
rel_kindnão é globalmente único entre todos os pares de tipos de objeto. Por exemplo,rel_kindpode sersubaccountpara um par de tipos de objeto epartner_accountpara outro. - Por isso, gravações de relacionamentos entre objetos exigem tanto
rel_kindquantorelated_type_name. Assim, é possível identificar o tipo de relacionamento pretendido junto com o outro tipo de objeto na associação. - Se o
related_type_namenão corresponder ao tipo de relacionamento daquelerel_kind, a solicitação retorna400.
anchor controla a direção do relacionamento
Os relacionamentos entre objetos são direcionais. O objeto da URL é interpretado com base no anchor.
anchor |
Papel do objeto da URL | Chave do objeto relacionado nas respostas |
|---|---|---|
source (padrão) |
Lado de origem (aresta de saída) | to_data_object |
target |
Lado de destino (aresta de entrada) | from_data_object |
Criar a mesma aresta a partir da perspectiva do anchor oposto ainda aponta para um único relacionamento subjacente. Uma segunda chamada de criação para a mesma aresta retorna 409 (duplicate-object-relationship).
Assimetria de caminhos para relacionamentos de usuário
As leituras e gravações de relacionamentos de usuário usam caminhos de endpoint diferentes de propósito:
- Leitura:
GET /data_objects/objects/{type_name}/{object_id}/user_relationships - Gravação:
POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users
Atributos de relacionamento são separados dos atributos de objeto
- Os endpoints de relacionamento retornam os atributos da aresta no campo
attributesde nível superior. - Os atributos do objeto ficam aninhados em
to_data_objectoufrom_data_object. PUTsubstitui osattributesdo relacionamento, ePATCHmescla osattributesdo relacionamento.
Exemplo prático
Este exemplo mostra um fluxo de trabalho comum de contas:
- Crie
account/acct-123. - Crie
account/acct-456como uma conta filha. - Vincule um usuário a
acct-123comrel_kind: account_user. - Vincule
acct-123aacct-456comrel_kind: subaccount.
Para consultar os vínculos:
GET /data_objects/objects/account/acct-123/user_relationshipspara usuários vinculadosGET /data_objects/objects/account/acct-123/object_relationshipspara vínculos de saída entre objetosGET /data_objects/objects/account/acct-456/object_relationships?anchor=targetpara vínculos de entrada entre objetos

Os endpoints DELETE para relacionamentos entre objetos e relacionamentos de usuário exigem um corpo de solicitação em JSON.
Endpoints em massa
Use os endpoints em massa para sincronizar objetos de dados, relacionamentos entre objetos e relacionamentos de usuários a partir dos seus próprios sistemas, em lotes. Cada solicitação cria, substitui ou exclui até 50 registros, e a Braze processa o lote em segundo plano.
| Método | Endpoint | Finalidade |
|---|---|---|
PUT |
/data_objects/objects |
Criar ou substituir até 50 objetos de dados, de qualquer combinação de tipos |
DELETE |
/data_objects/objects |
Excluir até 50 objetos de dados, de qualquer combinação de tipos |
PUT |
/data_objects/object_relationships |
Criar ou substituir até 50 relacionamentos entre objetos |
DELETE |
/data_objects/object_relationships |
Excluir até 50 relacionamentos entre objetos |
PUT |
/data_objects/user_relationships |
Criar ou substituir até 50 relacionamentos entre usuários e objetos |
DELETE |
/data_objects/user_relationships |
Excluir até 50 relacionamentos entre usuários e objetos |
Quando usar os endpoints em massa
Use os endpoints em massa quando você sincroniza muitos registros a partir dos seus próprios sistemas e não precisa que cada alteração seja aplicada antes de a resposta retornar. Use os endpoints de registro único quando precisar que a alteração fique visível na hora, quando precisar ler registros ou quando quiser atualizar apenas alguns atributos de um registro com PATCH.
Os endpoints em massa se diferenciam dos endpoints de registro único nos seguintes pontos:
- O processamento é assíncrono. Uma resposta
202significa que a Braze aceitou o lote e o colocou na fila, não que aplicou os registros. A Braze verifica se os tipos, os tipos de relacionamento, os objetos e os usuários existem, e se os atributos correspondem aos campos do tipo, quando processa o lote. Então, uma solicitação que retorna202ainda pode gerar falhas em registros individuais mais tarde. - A validação é do tipo tudo ou nada. Se qualquer registro de uma solicitação falhar na validação, a Braze rejeita a solicitação inteira com
400, não armazena nada e lista todos os erros. - 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. Quando duas solicitações alteram o mesmo registro, prevalece a que a Braze recebeu por último. - Os registros podem aguardar dependências. A exclusão de um objeto ou relacionamento que ainda não existe, e um relacionamento cujo objeto ou usuário ainda não existe, ficam em espera em vez de falhar na hora. A Braze tenta novamente por cerca de 40 horas (10 tentativas). Um upsert de objeto nunca fica em espera.
- Os endpoints em massa usam suas próprias permissões de chave de API e compartilham um limite de frequência de 1.000 solicitações por minuto por espaço de trabalho.
- Os endpoints em massa nunca criam tipos de objetos de dados. Todo
type_namejá precisa existir.
Os limites do produto se aplicam aos endpoints em massa da mesma forma que aos endpoints de registro único.
Paginação e atualização dos dados
Esta seção explica como funciona a paginação de listas e quando os dados ficam visíveis depois de uma gravação.
- Os endpoints de listagem aceitam
limiteoffset. - O padrão de
limité100, e o valor fica restrito ao intervalo de1a250. - O padrão de
offseté0, e valores negativos são arredondados para0. - Gravações de registro único ficam visíveis imediatamente para leituras e para a personalização com Liquid. As gravações em massa são aplicadas quando a Braze processa o lote na fila.
- A associação a um Segment com base em objetos de dados pode atrasar até uma hora, porque os filtros calculados são atualizados a cada hora.
Comportamento de erros
Esta seção resume os padrões de status e de resposta de erro usados nos endpoints de objetos de dados.
404,409,422e429retornam um arrayerrorscomidemessage.400,401e403retornam uma única stringerror.- Os endpoints em massa retornam os erros
400e500como um arrayerrorscomidemessage. Um erro400também inclui oparametercom problema, quando houver. Para erros no nível do registro, ele inclui ainda oindexdo registro. 422significa que a solicitação excederia um limite do produto. Os valores padrão dos limites variam de acordo com o contrato da empresa.