Endpoints des objets de données
Utilisez ces endpoints pour lister les types d’objets de données, gérer les enregistrements d’objets de données et gérer les relations entre objets et utilisateurs.

Les objets de données sont disponibles pour tous, mais votre espace de travail doit être provisionné pour les comptes avant que vous puissiez utiliser ces endpoints. Pour demander le provisionnement, accédez à Paramètres des données > Comptes et remplissez le questionnaire. Une fois le provisionnement terminé, les permissions de clé API des objets de données apparaissent dans Paramètres > Clés API. Pour plus de détails, consultez Activer les comptes.
Endpoints de type
Endpoints d’objet
Endpoints de relations entre objets
Endpoints de relations utilisateur
URL de base et authentification
Utilisez l’endpoint REST de votre espace de travail et envoyez Authorization: Bearer YOUR_REST_API_KEY. Cette section explique où sont hébergés les endpoints Data Objects et comment les requêtes sont authentifiées.
- Pour connaître les hôtes des endpoints, consultez l’aperçu de l’API de Braze.
- Tous les payloads de requête et de réponse sont au format JSON.
- Les requêtes sont limitées à l’espace de travail auquel appartient la clé API.
- Si la clé dispose d’une liste d’adresses IP autorisées, les adresses IP qui n’y figurent pas renvoient une erreur
403.
Autorisations des clés API
Cette section associe chaque endpoint à l’autorisation requise, afin que vous puissiez limiter la portée de vos clés API en toute sécurité.
| Autorisation | Groupe d’endpoints |
|---|---|
data_objects.read |
Lecture des types et des objets, et lecture des relations entre objets |
data_objects.create |
Création d’objets |
data_objects.update |
Remplacement et mise à jour d’objets |
data_objects.delete |
Suppression d’objets |
data_objects.user_relationships.read |
Lecture des relations utilisateur |
data_objects.user_relationships.create |
Création de relations utilisateur |
data_objects.user_relationships.update |
Remplacement et mise à jour de relations utilisateur |
data_objects.user_relationships.delete |
Suppression de relations utilisateur |
data_objects.object_relationships.create |
Création de relations entre objets |
data_objects.object_relationships.update |
Remplacement et mise à jour de relations entre objets |
data_objects.object_relationships.delete |
Suppression de relations entre objets |
data_objects.bulk_upsert |
Création ou remplacement d’objets en masse |
data_objects.bulk_delete |
Suppression d’objets en masse |
data_objects.object_relationships.bulk_upsert |
Création ou remplacement de relations entre objets en masse |
data_objects.object_relationships.bulk_delete |
Suppression de relations entre objets en masse |
data_objects.user_relationships.bulk_upsert |
Création ou remplacement de relations utilisateur en masse |
data_objects.user_relationships.bulk_delete |
Suppression de relations utilisateur en masse |

La lecture des relations entre objets utilise data_objects.read. Il n’existe pas d’autorisation data_objects.object_relationships.read.
Les endpoints en masse utilisent leurs propres autorisations, et l’upsert et la suppression font l’objet d’autorisations distinctes. Les autorisations portant sur un seul enregistrement, comme data_objects.create, ne donnent pas accès aux endpoints en masse.
Limites de débit
Cette section présente les quotas de requêtes par défaut et les en-têtes de réponse, pour le trafic en lecture comme en écriture.
| Compartiment | Limite par défaut |
|---|---|
| Lectures d’objets de données | 1 000 requêtes par minute |
| Écritures d’objets de données | 1 000 requêtes par minute |
| Écritures en masse d’objets de données | 1 000 requêtes par minute, partagées entre les six endpoints en masse et avec les synchronisations d’objets de données de l’ingestion de données cloud |
La limite d’écriture en masse s’applique par espace de travail et reste distincte de la limite d’écriture d’un enregistrement unique.
Chaque réponse inclut X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.
Lorsqu’une requête est limitée, Braze renvoie un code 429 et un payload d’erreur contenant id et message.
{
"errors": [
{
"id": "rate-limit-exceeded",
"message": "You have exceeded your limit of 1000 requests per minute."
}
]
}
Limites du produit
Cette section présente les limites que Braze applique aux Data Objects et ce qui se passe lorsque vous en atteignez une. Pour savoir comment ces limites s’appliquent aux enregistrements de comptes, consultez la section Limites des objets de compte.
Limites de quantité
Sauf mention contraire, ces limites s’appliquent à l’ensemble de votre entreprise. Il s’agit de capacités de départ. Si vous avez besoin de plus d’enregistrements ou d’une limite plus élevée, contactez votre équipe de compte Braze pour demander une augmentation.
| Limite | Valeur par défaut |
|---|---|
| Enregistrements d’objets de données par entreprise (sur l’ensemble des espaces de travail) | 50 000 |
| Champs par type d’objet de données | 500 |
| Objets de données liés à un même utilisateur | 1 000 |
| Utilisateurs liés à un même objet de données | 10 000 |
| Relations entre objets pour un même objet de données | 1 000 |
Limites des champs et des valeurs
Ces limites sont fixes pour toutes les entreprises.
| Limite | Valeur |
|---|---|
| Champs par type de relation (relations utilisateur et relations entre objets) | 25. Les champs de relation ne sont pas pris en compte dans la limite de champs par type d’objet de données. |
| Longueur des valeurs d’attribut | 255 caractères |
| Champs de date | Chaînes de caractères date-heure RFC 3339 qui incluent une heure et un fuseau horaire, par exemple 2026-11-03T00:00:00Z. Braze rejette les valeurs contenant uniquement une date, comme 2026-11-03. Pour plus de détails, consultez la section Format des champs de date. |
Longueur et format de l’object_id |
250 caractères. Lettres, chiffres, traits d’union et traits de soulignement uniquement. |
| Longueur et format des noms de champs | 250 caractères. Lettres, chiffres et traits de soulignement uniquement, sans commencer par un trait de soulignement. |
| Noms de champs réservés | id, external_id, object_id et display_name ne peuvent pas être utilisés comme noms de champs personnalisés. |
Format des champs de date
Les champs de date acceptent uniquement des chaînes de caractères date-heure RFC 3339 qui incluent à la fois une heure et un fuseau horaire. Braze exige la valeur complète afin de ne jamais avoir à deviner une heure ou un fuseau horaire. Si votre source stocke des valeurs contenant uniquement une date, comme des dates de renouvellement ou de contrat dans votre entrepôt de données, convertissez-les avant de les envoyer, par exemple dans la transformation de votre entrepôt.
| Valeur | Résultat |
|---|---|
2026-11-03T00:00:00Z |
Acceptée |
2026-11-03T00:00:00-05:00 |
Acceptée |
2026-11-03 |
Rejetée, car elle ne contient ni heure ni fuseau horaire |
2026-11-03T00:00:00 |
Rejetée, car elle ne contient pas de fuseau horaire |
Ce format s’applique aux champs de date des objets de données, des relations utilisateur et des relations entre objets. La manière dont Braze signale une valeur rejetée dépend de la façon dont vous l’envoyez :
- Les endpoints de création, de remplacement et de mise à jour d’un seul enregistrement renvoient
400. Si plusieurs attributs ne sont pas valides, l’erreur ne mentionne que le premier. - Les endpoints d’upsert en masse acceptent la requête avec
202, puis enregistrent un échec de traitementdata-object-schema-mismatchpour l’enregistrement, par exempleattributes: renewal_date is not valid for its field. - Les synchronisations Cloud Data Ingestion utilisent le même traitement que les endpoints en masse : Braze n’applique donc pas une ligne contenant une valeur avec uniquement une date, et l’échec apparaît dans les logs de synchronisation.
Par exemple, une requête portant sur un seul enregistrement qui envoie 2026-11-03 pour un champ de date renewal_date renvoie cette réponse 400 :
{
"error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}
Que se passe-t-il lorsque vous atteignez une limite ?
Une requête qui dépasserait une limite de quantité renvoie 422 avec un id d’erreur qui identifie la limite concernée :
{
"errors": [
{
"id": "data-object-record-limit-exceeded",
"message": "This company has reached its data object record limit"
}
]
}
| Limite | id d’erreur |
|---|---|
| Enregistrements d’objets de données par entreprise | data-object-record-limit-exceeded |
| Champs par type d’objet de données | data-object-field-limit-exceeded |
| Champs par type de relation | data-object-field-limit-exceeded |
| Objets de données liés à un même utilisateur | data-objects-per-user-limit-exceeded |
| Utilisateurs liés à un même objet de données | users-per-data-object-limit-exceeded |
| Relations entre objets pour un même objet de données | data-object-relationship-limit-exceeded |
Vos enregistrements et relations existants restent en place : seule la requête qui dépasserait la limite est rejetée. Pour libérer de la place sous une limite, supprimez les enregistrements dont vous n’avez plus besoin ou retirez les relations que vous n’utilisez plus. Pour augmenter une limite de quantité, contactez votre équipe de compte Braze.
Les requêtes dont la validation échoue, par exemple en raison d’un object_id ou d’une valeur d’attribut trop long, renvoient 400. Les requêtes qui dépassent la limite de débit renvoient 429.
Concepts fondamentaux
Cette section définit les principaux identifiants utilisés dans tous les endpoints des objets de données.
type_name: Le nom machine du type d’objet de données, unique au sein d’un espace de travail.object_id: L’identifiant de votre objet, unique au sein d’un type.user: L’utilisateur concerné par une requête d’écriture de relation utilisateur, identifié par un seul et unique élément parmiexternal_id,braze_id,alias,emailouphone.attributes: Les données de l’objet ou de la relation, indexées par nom de champ et validées par rapport au schéma configuré.
Fonctionnement des relations
Cette section présente les types de relations, les arêtes de relation et le comportement d’anchor avant que vous n’utilisiez les pages de référence des endpoints.
Aperçu du modèle de relations
Ce diagramme montre comment s’articulent les types, les enregistrements et les relations, et ce que leur liaison vous permet de faire dans Braze. Vous définissez les types dans le tableau de bord, puis vous écrivez les enregistrements et les liens entre eux à l’aide de ces 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
Les types et les arêtes sont distincts
- Les types de relations définissent les liens valides et sont gérés dans le tableau de bord.
- Les arêtes de relation sont les liens réels entre les enregistrements. Elles sont créées, mises à jour et supprimées via ces endpoints de l’API.
- Avant d’écrire des relations, listez les valeurs
rel_kindvalides avec :GET /data_objects/types/{type_name}/user_relationship_typesGET /data_objects/types/{type_name}/object_relationship_types
Pourquoi les relations entre objets nécessitent related_type_name
rel_kindn’est pas unique à l’échelle de toutes les paires de types d’objets. Par exemple,rel_kindpeut valoirsubaccountpour une paire de types d’objets etpartner_accountpour une autre.- Les écritures de relations entre objets nécessitent donc à la fois
rel_kindetrelated_type_namepour identifier le type de relation visé ainsi que l’autre type d’objet de l’association. - Si
related_type_namene correspond pas au type de relation associé à cerel_kind, la requête renvoie400.
anchor détermine le sens de la relation
Les relations entre objets sont orientées. L’objet indiqué dans l’URL est interprété en fonction d’anchor.
anchor |
Rôle de l’objet de l’URL | Clé de l’objet associé dans les réponses |
|---|---|---|
source (par défaut) |
Côté origine (arête sortante) | to_data_object |
target |
Côté destination (arête entrante) | from_data_object |
Créer la même arête depuis la perspective d’ancrage opposée vise toujours une seule et même relation sous-jacente. Un second appel de création pour la même arête renvoie 409 (duplicate-object-relationship).
Asymétrie des chemins pour les relations utilisateur
Les lectures et écritures de relations utilisateur utilisent volontairement des chemins d’endpoint différents :
- Lecture :
GET /data_objects/objects/{type_name}/{object_id}/user_relationships - Écriture :
POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users
Les attributs de relation sont distincts des attributs d’objet
- Les endpoints de relation renvoient les attributs propres à l’arête dans le champ
attributesde premier niveau. - Les attributs d’objet restent imbriqués sous
to_data_objectoufrom_data_object. PUTremplace lesattributesde la relation, tandis quePATCHles fusionne.
Exemple concret
Cet exemple illustre un flux de travail courant autour des comptes :
- Créez
account/acct-123. - Créez
account/acct-456en tant que compte enfant. - Liez un utilisateur à
acct-123avecrel_kind: account_user. - Liez
acct-123àacct-456avecrel_kind: subaccount.
Pour relire les liens :
GET /data_objects/objects/account/acct-123/user_relationshipspour les utilisateurs liésGET /data_objects/objects/account/acct-123/object_relationshipspour les liens d’objets sortantsGET /data_objects/objects/account/acct-456/object_relationships?anchor=targetpour les liens d’objets entrants

Les endpoints DELETE des relations entre objets et des relations utilisateur nécessitent un corps de requête JSON.
Endpoints en masse
Utilisez les endpoints en masse pour synchroniser par lots les objets de données, les relations entre objets et les relations avec les utilisateurs depuis vos propres systèmes. Chaque requête crée, remplace ou supprime jusqu’à 50 enregistrements, et Braze traite le lot en arrière-plan.
| Méthode | Endpoint | Objectif |
|---|---|---|
PUT |
/data_objects/objects |
Créer ou remplacer jusqu’à 50 objets de données, de types éventuellement différents |
DELETE |
/data_objects/objects |
Supprimer jusqu’à 50 objets de données, de types éventuellement différents |
PUT |
/data_objects/object_relationships |
Créer ou remplacer jusqu’à 50 relations entre objets |
DELETE |
/data_objects/object_relationships |
Supprimer jusqu’à 50 relations entre objets |
PUT |
/data_objects/user_relationships |
Créer ou remplacer jusqu’à 50 relations entre utilisateurs et objets |
DELETE |
/data_objects/user_relationships |
Supprimer jusqu’à 50 relations entre utilisateurs et objets |
Quand utiliser les endpoints en masse
Utilisez les endpoints en masse lorsque vous synchronisez de nombreux enregistrements depuis vos propres systèmes et que vous n’avez pas besoin que chaque modification soit appliquée avant le retour de la réponse. Utilisez les endpoints à enregistrement unique lorsque la modification doit être visible immédiatement, lorsque vous devez lire des enregistrements ou lorsque vous souhaitez mettre à jour seulement certains attributs d’un enregistrement avec PATCH.
Les endpoints en masse se distinguent des endpoints à enregistrement unique sur les points suivants :
- Le traitement est asynchrone. Une réponse
202signifie que Braze a accepté le lot et l’a mis en file d’attente, et non qu’il a appliqué les enregistrements. Braze vérifie l’existence des types, des types de relations, des objets et des utilisateurs, ainsi que la correspondance des attributs avec les champs du type, au moment où il traite le lot. Une requête qui renvoie202peut donc encore produire des échecs pour certains enregistrements par la suite. - La validation suit le principe du tout ou rien. Si un seul enregistrement d’une requête échoue à la validation, Braze rejette l’ensemble de la requête avec une erreur
400, n’enregistre rien et liste toutes les erreurs. - Les enregistrements sont ordonnés selon leur heure de réception. Braze horodate chaque enregistrement avec l’heure à laquelle il a reçu la requête : n’envoyez donc pas
updated_at. Lorsque deux requêtes modifient le même enregistrement, c’est celle que Braze a reçue en dernier qui l’emporte. - Les enregistrements peuvent attendre leurs dépendances. La suppression d’un objet ou d’une relation qui n’existe pas encore, ainsi qu’une relation dont l’objet ou l’utilisateur n’existe pas encore, sont mises en attente au lieu d’échouer immédiatement. Braze effectue de nouvelles tentatives pendant environ 40 heures (10 tentatives). Un upsert d’objet n’est jamais mis en attente.
- Les endpoints en masse utilisent leurs propres autorisations de clé API et partagent une limite de débit de 1 000 requêtes par minute et par espace de travail.
- Les endpoints en masse ne créent jamais de types d’objets de données. Chaque
type_namedoit déjà exister.
Les limites du produit s’appliquent aux endpoints en masse de la même manière qu’aux endpoints à enregistrement unique.
Pagination et fraîcheur des données
Cette section décrit le fonctionnement de la pagination des listes et le délai attendu avant que les données soient visibles après une écriture.
- Les endpoints de liste prennent en charge
limitetoffset. limita pour valeur par défaut100et est limité à une plage allant de1à250.offseta pour valeur par défaut0, et les valeurs négatives sont ramenées à0.- Les écritures d’un seul enregistrement sont immédiatement visibles pour les lectures et la personnalisation Liquid. Les écritures en masse sont appliquées lorsque Braze traite le lot mis en file d’attente.
- L’appartenance aux Segments basée sur des objets de données peut présenter un décalage allant jusqu’à une heure, car les filtres calculés sont actualisés toutes les heures.
Comportement en cas d’erreur
Cette section résume les codes de statut et les formats de réponse d’erreur utilisés par l’ensemble des endpoints Data Objects.
- Les codes
404,409,422et429renvoient un tableauerrorscontenantidetmessage. - Les codes
400,401et403renvoient une seule chaîne de caractèreserror. - Les endpoints en masse renvoient les erreurs
400et500sous la forme d’un tableauerrorscontenantidetmessage. Une erreur400inclut également leparameteren cause, le cas échéant, et, pour les erreurs au niveau d’un enregistrement, l’indexde cet enregistrement. - Le code
422signifie que la requête dépasserait une limite du produit. Les valeurs limites par défaut varient selon le contrat de l’entreprise.