Créer une relation utilisateur
/data_objects/objects/{type_name}/{object_id}/users
Utilisez cet endpoint pour associer un utilisateur Braze à un objet de données.

Les objets de données sont en disponibilité générale, mais votre espace de travail doit être provisionné pour les comptes avant de pouvoir utiliser cet endpoint. Pour demander le provisionnement, accédez à Paramètres des données > Comptes et remplissez le questionnaire. Pour plus de détails, consultez la section Activer les comptes.
Prérequis
Pour utiliser cet endpoint, vous avez besoin d’une clé API disposant de la permission data_objects.user_relationships.create.
Limite de débit
Cet endpoint fait partie du compartiment d’écriture des objets de données, avec une limite par défaut de 1 000 requêtes par minute.
Paramètres de chemin
Le tableau suivant répertorie et décrit les paramètres de chemin de l’endpoint /data_objects/objects/{type_name}/{object_id}/users.
| Paramètre | Obligatoire | Type de données | Description |
|---|---|---|---|
type_name |
Obligatoire | Chaîne de caractères | Type d’objet |
object_id |
Obligatoire | Chaîne de caractères | Identifiant de l’objet |
Paramètres de requête
Le tableau suivant répertorie et décrit les paramètres du corps de requête JSON de l’endpoint /data_objects/objects/{type_name}/{object_id}/users.
| Paramètre | Obligatoire | Type de données | Description |
|---|---|---|---|
user |
Obligatoire | Objet | L’utilisateur à associer à l’objet. Doit contenir exactement un identifiant parmi external_id, braze_id, alias, email ou phone. |
user.external_id |
Facultatif | Chaîne de caractères | L’ID externe de l’utilisateur. |
user.braze_id |
Facultatif | Chaîne de caractères | L’ID utilisateur Braze. |
user.alias |
Facultatif | Objet | Objet alias d’utilisateur contenant alias_name et alias_label (tous deux obligatoires s’il est utilisé). |
user.email |
Facultatif | Chaîne de caractères | L’adresse e-mail de l’utilisateur. |
user.phone |
Facultatif | Chaîne de caractères | Le numéro de téléphone de l’utilisateur. Doit pouvoir être converti au format E.164. |
rel_kind |
Obligatoire | Chaîne de caractères | Type de relation |
attributes |
Facultatif | Objet | Attributs de la relation |
Identification de l’utilisateur
- Transmettez exactement un identifiant dans
user. Si aucun identifiant non nul n’est fourni, ou s’il y en a plusieurs, la requête renvoie400. Les champs d’identifiant nuls accompagnant un identifiant valide sont acceptés. - Si une adresse e-mail ou un numéro de téléphone correspond à plusieurs profils utilisateur, Braze sélectionne l’utilisateur identifié (celui qui possède un
external_id). En cas d’égalité persistante, Braze sélectionne le profil mis à jour le plus récemment. - Utilisez
external_idlorsqu’il est disponible.
Exemple de requête
Cette section comprend un exemple de payload JSON et un exemple de requête cURL.
Exemple de payload de requête
{
"user": {
"external_id": "user-123"
},
"rel_kind": "account_user",
"attributes": {
"role": "owner"
}
}
Autre exemple utilisant un alias d’utilisateur :
{
"user": {
"alias": {
"alias_name": "[email protected]",
"alias_label": "crm_email"
}
},
"rel_kind": "account_user",
"attributes": {
"role": "owner"
}
}
Exemple de requête cURL
Cet exemple associe un utilisateur à acct-123 en tant qu’account_user et enregistre son role comme owner.
curl --location --request POST 'https://rest.iad-01.braze.com/data_objects/objects/account/acct-123/users' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"user": {
"external_id": "user-123"
},
"rel_kind": "account_user",
"attributes": {
"role": "owner"
}
}'
Réponse
Cette section comprend un exemple de réponse réussie et les champs de la réponse.
Exemple de réponse réussie
Le code de statut 201 peut renvoyer le corps de réponse suivant.
{
"user_relationship": {
"type_name": "account",
"object_id": "acct-123",
"rel_kind": "account_user",
"user": {
"external_id": "user-123",
"braze_id": "507f1f77bcf86cd799439011"
},
"attributes": { "role": "owner" }
}
}
Paramètres de réponse
Le tableau suivant répertorie et décrit les champs d’une réponse réussie.
| Paramètre | Obligatoire | Type de données | Description |
|---|---|---|---|
user_relationship |
Obligatoire | Objet | Enregistrement de la relation utilisateur créée |
user_relationship.type_name |
Obligatoire | Chaîne de caractères | Nom machine du type d’objet de données |
user_relationship.object_id |
Obligatoire | Chaîne de caractères | Identifiant de l’objet de données |
user_relationship.rel_kind |
Obligatoire | Chaîne de caractères | Valeur du type de relation |
user_relationship.user |
Obligatoire | Objet | Objet utilisateur associé contenant l’identifiant tel qu’envoyé, ainsi que braze_id |
user_relationship.attributes |
Obligatoire | Objet | Attributs de la relation (toujours présents ; objet vide s’il n’y en a aucun) |
Erreurs
Le tableau suivant répertorie les erreurs courantes de cet endpoint et la manière de les résoudre.
| Statut | Cause | Recommandation |
|---|---|---|
400 |
user manquant ou vide, aucun identifiant, plusieurs identifiants, identifiant vide, braze_id, email ou alias mal formé, numéro de téléphone non convertible au format E.164, ou ancien corps avec braze_id au niveau racine |
Envoyez un objet user contenant exactement un identifiant valide. |
400 |
rel_kind inconnu pour le type ou erreur de validation du schéma |
Vérifiez que rel_kind est valide pour le type d’objet et que les attributes correspondent au schéma de la relation. |
404 |
Type, objet ou utilisateur introuvable (user-not-found) |
Vérifiez que type_name et object_id existent dans l’espace de travail et que l’utilisateur existe avec cet identifiant. |
409 |
Relation en double (duplicate-user-relationship) |
Utilisez PUT pour remplacer la relation existante, ou supprimez-la avant de la recréer. |
422 |
Limite d’objets par utilisateur atteinte (data-objects-per-user-limit-exceeded) ou limite d’utilisateurs par objet atteinte (users-per-data-object-limit-exceeded) |
Réduisez le nombre de relations de l’utilisateur ou de l’objet, ou contactez le support Braze au sujet des limites de votre espace de travail. |
401 |
Clé REST API manquante ou invalide | Vérifiez que l’en-tête Authorization utilise Bearer YOUR_REST_API_KEY et que la clé est active. |
403 |
La clé API ne dispose pas de la permission requise ou la requête est bloquée par la liste d’autorisation | Vérifiez que la clé dispose de la permission data_objects.user_relationships.create et que votre adresse IP source figure dans la liste d’autorisation de la clé, si celle-ci est configurée. |
429 |
Limite de débit dépassée | Réessayez après X-RateLimit-Reset et réduisez la fréquence des requêtes. |