> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.fr/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API du CRM | Associations v4
> Les points de terminaison pour les associations de CRM sont utilisés pour gérer les associations entre des tickets, des produits, des lignes de produit et leurs contacts, entreprises et transactions associés.
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Cette API requiert l'une des portées suivantes :"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
# Associations v4
Pour la version précédente, veuillez consulter la documentation de [l’API d’associations v3](/api-reference/crm-associations-v3/guide).
Les associations représentent les relations entre les objets et les activités dans le CRM de HubSpot. Des associations de fiches d’informations peuvent exister entre des fiches d’informations de différents objets (par exemple : de Contact à Entreprise) ou au sein d’un même objet (par exemple : Entreprise à Entreprise). Vous pouvez utiliser les points de terminaison d'associations pour créer, récupérer, mettre à jour, ou supprimer des associations entre des fiches d'informations, ou des fiches d'informations et des activités.
Les points de terminaison de schéma d’association vous permettent d’afficher les types d’association pris en charge dans votre compte, ainsi que de créer vos propres types d’association et d’attribuer des libellés à vos relations de fiche d’informations. Les libellés d’association sont pris en charge entre les contacts, les entreprises, les transactions, les tickets et les objets personnalisés, et peuvent être [utilisés dans tous les outils HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#use-association-labels-in-hubspot-tools) tels que les listes et les workflows.
Découvrez-en davantage sur les API d'objets, de fiches d'informations, de propriétés et d'associations dans le [guide Comprendre le CRM](/guides/crm/understanding-the-crm).
### Remarque:
L’API d’associations v4 est prise en charge dans la version 9.0.0 ou ultérieure du client NodeJS HubSpot.
## HubSpot a défini des types d’association
HubSpot fournit un ensemble de types d’association prédéfinis (par exemple : contact sans libellé de l’entreprise), mais les administrateurs de compte peuvent [définir leurs propres libellés d’association](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) pour fournir un contexte supplémentaire pour les relations entre les fiches d’informations (par exemple : responsable et employé). Il existe deux types d’association définis par HubSpot :
* **Principale** : l’entreprise principale à laquelle l’autre fiche d’informations est associée. Les associations principales peuvent être utilisées dans les outils HubSpot tels que [les listes et les workflows](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#use-associations-in-hubspot-tools). Pour les fiches d’informations contenant plusieurs entreprises associées, cette API prend en charge la modification de l’entreprise considérée comme principale.
* **Sans libellé** : un type d’association ajouté lorsqu’une fiche d’informations de contact, d’entreprise, de transaction, de ticket ou d’objet personnalisé est associée. Ce type indique qu’une association existe et sera toujours renvoyée dans les réponses avec une valeur de **libellé** de `null`. Lorsqu’une fiche d’informations dispose d’une association principale ou d’un libellé d’association personnalisé, ces types seront répertoriés avec le type d’association sans libellé.
Vous pouvez visualiser tous les types d’association définis par HubSpot dans [cette section](#association-type-id-values).
## Libellés simples ou jumelés
Il existe deux types de [libellés d’association](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) que vous pouvez utiliser pour décrire les relations entre des fiches d’informations :
* **Unique** : un libellé qui s’applique aux deux fiches d’informations de la relation. Par exemple : *Ami* ou *Collègue*.
* **Jumelé** : une paire de libellés pour les cas où des mots différents sont utilisés pour décrire chaque aspect de la relation des fiches d’informations associées. Par exemple : *Parent* et *Enfant* ou *Employeur* et *Employé*. Pour créer des libellés appariés, vous devez inclure le champ `inverseLabel` dans votre demande pour nommer le deuxième libellé de la paire.
## Créer des types d’association
Vous pouvez créer des types d’association personnalisés [dans HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) ou via le point de terminaison d’API du schéma d’association. Vous pouvez créer jusqu’à 10 types d’association entre chaque paire d’objets (par exemple : contacts et entreprises, contacts et contacts).
Pour créer un type d’association via l’API, effectuez une demande `POST` à `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels` et incluez les éléments suivants dans votre demande :
* **nom** : le nom interne du type d’association. Cette valeur ne peut pas comprendre de traits d’union ni commencer par un caractère numérique.
* **libellé** : le nom du [libellé d’association tel qu’il apparaît dans HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels).
* **inverseLabel** (libellés jumelés uniquement) : le nom du deuxième libellé de la paire de libellés.
Par exemple, votre demande pourrait ressembler à ce qui suit :
```json theme={null}
///Example request body - Single label
{
"label": "Partner",
"name": "partner"
}
```
```json theme={null}
///Example request body - Paired labels
{
"label": "Manager",
"inverseLabel": "Employee",
"name": "manager_employee"
}
```
## Récupérer les types d’association
Pour afficher les types d’association entre des objets spécifiques, effectuez une demande `GET` à `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels`.
Vous recevrez un tableau contenant chaque élément :
* **catégorie** : si le type d’association a été créé par HubSpot (`HUBSPOT_DEFINED`) ou par un utilisateur (`USER_DEFINED`).
* \*\*typeId: \*\* l’ID numérique pour ce type d’association. Ceci est utilisé pour [définir un libellé lors de l’association de fiches d’informations](#associate-with-label). Consultez [cette liste](#association-type-id-values) pour toutes les valeurs `typeId` définies par HubSpot.
* **libellé** : le libellé alphanumérique. Il s’agit de la valeur `null` du type d’association sans libellé.
Vous pouvez également trouver ces valeurs dans HubSpot [dans vos paramètres d’association](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#association-label-api-details).
## Associer des fiches d'informations
### Associer des fiches d'informations sans libellé
Vous pouvez créer une association sans libellé par défaut entre deux fiches d’informations ou configurer des associations sans libellé pour des fiches d’informations en masse. Pour configurer une association individuelle par défaut entre deux fiches d’informations, effectuez une demande `PUT` à
`/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}`
Dans l'URL de la demande, comprend :
* `fromObjectType`\*\* :\*\* l'ID de l'objet que vous associez. Pour trouver les valeurs d’ID, consultez cette [liste d’ID de types d’objet,](/guides/crm/understanding-the-crm#object-type-id) ou pour les contacts, les entreprises, les transactions, les tickets et les notes, vous pouvez utiliser le nom d’objet (par exemple : `contact`, `company`).
* `fromObjectId`\*\* :\*\* l’ID de la fiche d’informations à associer.
* `toObjectType`\*\* :\*\* l'ID de l'objet auquel vous associez la fiche d'informations. Pour trouver les valeurs d’ID, consultez cette [liste d’ID de types d’objet,](/guides/crm/understanding-the-crm#object-type-id) ou pour les contacts, les entreprises, les transactions, les tickets et les notes, vous pouvez utiliser le nom d’objet (par exemple : `contact`, `company`).
* `toObjectId`\*\* :\*\* l’ID de la fiche d’informations à associer.
Par exemple : pour associer une fiche d’informations de contact dont l’ID est 12345 à une fiche d’informations d’entreprise dont l’ID est `67891`, l’URL de votre demande sera : `/crm/v4/objects/contact/12345/associations/default/company/67891`.
Pour configurer des associations par défaut en masse, effectuez une demande `POST` à `crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default`. Dans le corps de la demande, incluez les valeurs `objectId` des fiches d’informations que vous souhaitez associer.
### Remarque:
Le nombre d’associations qu’une fiche d’informations peut avoir dépend de [l’objet et de votre abonnement HubSpot.](https://legal.hubspot.com/hubspot-product-and-services-catalog#TechnicalLimits:~:text=CRM%20Record%20Association%20Limits)
### Associer des fiches d'informations avec libellé
Pour associer deux fiches d’informations et définir un libellé pour décrire l’association, effectuez une demande `PUT` à `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}`. Dans le corps de la demande, incluez `associationCategory` et `associationTypeId` pour indiquer le type d’association que vous souhaitez créer.
Si vous créez des associations sans libellé, vous pouvez utiliser les points de terminaison par défaut décrits dans la [section ci-dessus](#associate-records-without-a-label), qui ne nécessitent pas `associationCategory` ou `associationTypeId`. Si vous créez des associations avec un libellé, vous pouvez consultez cette [liste d’ID de type par défaut](#association-type-id-values) ou vous devrez récupérer les types d’association personnalisés entre ces objets.
### Remarque:
Pour les relations entre les objets croisés et les libellés jumelés, assurez-vous d’utiliser la méthode `typeId` qui renvoie à la bonne direction (par exemple : Contact à Entreprise vs Entreprise à Contact, Employé à Responsable ou Responsable à Employé).
Par exemple : pour associer un contact à une transaction à l’aide d’un libellé personnalisé :
1\. Effectuez une demande `GET` à `/crm/v4/associations/contact/deal/labels`.
2\. Dans la réponse, examinez les valeurs `typeId` et `category` du libellé. L’ID sera un nombre (par exemple : `36`) et la catégorie sera toujours `USER_DEFINED` pour les libellés personnalisés.
3\. Effectuez une demande `PUT` à `/crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}` avec le corps de requête suivant :
```json theme={null}
/// Example request body
[
{
"associationCategory": "USER_DEFINED",
"associationTypeId": 36
}
]
```
## Définir et gérer des limites d’association
Vous pouvez définir des [limites](https://knowledge.hubspot.com/object-settings/set-limits-for-record-associations) pour le nombre de fiches d’informations associées entre les objets ou la fréquence à laquelle un libellé peut être utilisé pour décrire les associations. Il existe également [des limites techniques et des limites en fonction de votre abonnement HubSpot](https://legal.hubspot.com/hubspot-product-and-services-catalog).
### Créer ou mettre à jour des limites d’association
Vous pouvez créer de nouvelles limites d’association ou mettre à jour celles qui existent déjà entre des objets.
* Pour créer des limites, effectuez une demande `POST` à `crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create`.
* Pour mettre à jour les limites existantes, effectuez une demande `POST` à `crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update`.
Dans le corps de la demande, ajoutez `inputs` aux éléments suivants :
| Paramètre | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | La catégorie de l’association pour laquelle vous définissez une limite, soit `HUBSPOT_DEFINED` ou `USER_DEFINED`. |
| `typeId` | L’ID numérique du type d’association pour lequel vous souhaitez définir une limite. Consultez [cette liste](#association-type-id-values) de valeurs `typeId` par défaut ou [récupérez la valeur](#retrieve-association-types) pour les libellés personnalisés. |
| `maxToObjectIds` | Le nombre maximal d’associations autorisé pour le type d’association. |
Par exemple, pour définir des limites auxquelles une transaction peut être associée à un maximum de cinq contacts, avec un seul contact intitulé *Point de contact* pour une transaction, votre demande ressemblerait à ce qui suit :
```json theme={null}
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/create
{
"inputs": [
{
"category": "HUBSPOT_DEFINED",
"typeId": 3,
"maxToObjectIds": 5
},
{
"category": "USER_DEFINED",
"typeId": 35,
"maxToObjectIds": 1
}
]
}
```
### Récupérer les limites d’association
* Pour lire toutes les limites d’association définies, effectuez une demande `GET` à `/crm/v4/associations/definitions/configurations/all`. Cela renverra des limites d’association personnalisées définies pour tous les objets.
* Pour lire les limites d’association entre deux objets spécifiques, effectuez une demande `GET` à `/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}`.
Pour les deux demandes, la réponse renverra les valeurs des associations pour `category`, `typeId`, `maxToObjectIds` et `label`. Par exemple, si vous récupérez les limites entre les transactions et les contacts, la réponse ressemblera à ceci :
```json theme={null}
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
"results": [
{
"category": "HUBSPOT_DEFINED",
"typeId": 3,
"userEnforcedMaxToObjectIds": 5,
"label": null
}
]
}
```
### Supprimer les limites d’association
Pour supprimer des limites d’association spécifiques, effectuez une demande `POST` à `/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge`. Dans le corps de la demande, incluez les valeurs `category` et `typeId` des types d’association pour lesquels vous souhaitez supprimer les limites.
Par exemple, pour supprimer la limite *Point de contact* entre les transactions et les contacts, la demande ressemblerait à ceci :
```json theme={null}
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/purge
{
"inputs": [
{
"category": "USER_DEFINED",
"typeId": 35
}
]
}
```
En cas de réussite, vous recevrez une réponse 204 et la limite incluse reviendra au système par défaut (c’est-à-dire que de nombreux contacts peuvent avoir le libellé *Point de contact*).
## Rapport sur l’utilisation fréquente des associations
Il existe des [limites techniques au nombre d’associations qu’une fiche d’informations peut avoir](https://legal.hubspot.com/hubspot-product-and-services-catalog). Vous pouvez utiliser l’API d’associations pour récupérer un rapport de fiches d’informations qui approchent ou ont atteint la limite maximale pour les associations.
Pour récupérer le rapport, effectuez une demande `POST` à `crm/v4/associations/usage/high-usage-report/{userID}`. Le fichier contient des fiches d’informations utilisant 80 % ou plus de leur limite d’association. Par exemple, si une entreprise peut être associée à un maximum de 50 000 contacts, elle sera incluse dans le fichier si elle compte 40 000 contacts associés ou plus. Le fichier sera envoyé à l’e-mail de l’utilisateur dont l’ID a été inclus dans l’URL de la demande. Découvrez comment récupérer des ID utilisateur avec [l’API d’utilisateurs](/api-reference/settings-user-provisioning-v3/guide).
## Valeurs d’ID de type d’association
Les tableaux suivants incluent les valeurs `associationTypeId` définies par HubSpot qui précisent le type d’association. Les types d’associations varient en fonction des objets inclus et de la direction de l’association (par exemple : Contact à Entreprise est différent de Entreprise à Contact). Si vous créez des objets personnalisés ou des libellés d’association personnalisés, les types d’association associés auront des valeurs `typeId` uniques que vous devrez [récupérer](#retrieve-association-type) ou localiser dans vos [paramètres d’association dans HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#association-label-api-details).
### Remarque:
Les types d’association d’entreprise par défaut incluent un type d’association sans libellé et un type d’association principal. Si une fiche d’informations a plusieurs entreprises associées, une seule peut être l’entreprise principale. Les autres associations peuvent être sans libellé ou avoir des libellés d’association personnalisés.
#### Contact à objet
| ID DU TYPE | Type d'association |
| ---------- | ----------------------------------------------------------- |
| `449` | Contact à contact |
| `279` | Contact à entreprise |
| `1` | Contact à entreprise (principal) |
| `4` | Contact à transaction |
| `15` | Contact à ticket |
| `193` | Contact à appel |
| `197` | Contact à e-mail |
| `199` | Contact à réunion |
| `201` | Contact à note |
| `203` | Contact à tâche |
| `82` | Contact à communication (message SMS, WhatsApp ou LinkedIn) |
| `454` | Contact à courrier postal |
| `587` | Contact à panier |
| `508` | Contact à commande |
| `178` | Contact à facture |
| `388` | Contact à paiement |
| `296` | Contact à abonnement |
#### Entreprise à objet
| ID DU TYPE | Type d'association |
| ---------- | -------------------------------------------------------------- |
| `450` | Entreprise à entreprise |
| `14` | Enfant à entreprise parent |
| `13` | Parent à entreprise enfant |
| `280` | Entreprise à contact |
| `2` | Entreprise à contact (principal) |
| `342` | Entreprise à transaction |
| `6` | Entreprise à transaction (principal) |
| `340` | Entreprise à ticket |
| `25` | Entreprise à ticket (principal) |
| `181` | Entreprise à appel |
| `185` | Entreprise à e-mail |
| `187` | Entreprise à réunion |
| `189` | Entreprise à note |
| `191` | Entreprise à tâche |
| `88` | Entreprise à communication (message SMS, WhatsApp ou LinkedIn) |
| `460` | Entreprise à courrier postal |
| `180` | Entreprise à facture |
| `510` | Entreprise à commande |
| `390` | Entreprise à paiement |
| `298` | Entreprise à abonnement |
#### Transaction à objet
| ID DU TYPE | Type d'association |
| ---------- | --------------------------------------------------------------- |
| `451` | Transaction à transaction |
| `3` | Transaction à contact |
| `341` | Transaction à entreprise |
| `5` | Transaction à entreprise (principal) |
| `27` | Transaction à ticket |
| `205` | Transaction à appel |
| `209` | Transaction à e-mail |
| `211` | Transaction à réunion |
| `213` | Transaction à note |
| `215` | Transaction à tâche |
| `86` | Transaction à communication (message SMS, WhatsApp ou LinkedIn) |
| `458` | Transaction à courrier postal |
| `313` | Transaction à répartition de transaction |
| `19` | Transaction à ligne de produit |
| `176` | Transaction à facture |
| `511` | Transaction à commande |
| `392` | Transaction à paiement |
| `630` | Transaction à produit |
| `63` | Transaction à devis |
| `300` | Transaction à abonnement |
#### Ticket à objet
| ID DU TYPE | Type d'association |
| ---------- | ---------------------------------------------------------- |
| `452` | Ticket à ticket |
| `16` | Ticket à contact |
| `339` | Ticket à entreprise |
| `26` | Ticket à entreprise (principal) |
| `28` | Ticket à transaction |
| `219` | Ticket à appel |
| `223` | Ticket à e-mail |
| `223` | Ticket à réunion |
| `227` | Ticket à note |
| `229` | Ticket à tâche |
| `84` | Ticket à communication (message SMS, WhatsApp ou LinkedIn) |
| `456` | Ticket à courrier postal |
| `32` | Ticket à fil de conversation |
| `278` | Ticket à conversation |
| `526` | Ticket à commande |
### Lead à objet
| ID DU TYPE | Type d'association |
| ---------- | ------------------------ |
| `578` | Lead à contact principal |
| `596` | Lead à appel |
| `598` | Lead à e-mail |
| `600` | Lead à réunion |
| `602` | Lead à communication |
| `608` | Lead à contact |
| `610` | Lead à entreprise |
| `646` | Lead à tâche |
#### Appel à objet
| ID DU TYPE | Type d'association |
| ---------- | ------------------- |
| `194` | Appel à contact |
| `182` | Appel à entreprise |
| `206` | Appel à transaction |
| `220` | Appel à ticket |
#### E-mail à objet
| ID DU TYPE | Type d'association |
| ---------- | -------------------- |
| `198` | E-mail à contact |
| `186` | E-mail à entreprise |
| `210` | E-mail à transaction |
| `224` | E-mail à ticket |
#### Réunion à objet
| ID DU TYPE | Type d'association |
| ---------- | --------------------- |
| `200` | Réunion à contact |
| `188` | Réunion à entreprise |
| `212` | Réunion à transaction |
| `226` | Réunion à ticket |
#### Note à objet
| ID DU TYPE | Type d'association |
| ---------- | ------------------ |
| `202` | Note à contact |
| `190` | Note à entreprise |
| `214` | Note à transaction |
| `228` | Note à ticket |
#### Courrier postal à objet
| ID DU TYPE | Type d'association |
| ---------- | ----------------------------- |
| `453` | Courrier postal à contact |
| `459` | Courrier postal à entreprise |
| `457` | Courrier postal à transaction |
| `455` | Courrier postal à ticket |
#### Devis à objet
| ID DU TYPE | Type d'association |
| ---------- | --------------------------------------------------------- |
| `69` | Devis à contact |
| `71` | Devis à entreprise |
| `64` | Devis à transaction |
| `67` | Devis à ligne de produit |
| `286` | Devis à modèle de devis |
| `362` | Devis à remise |
| `364` | Devis à frais |
| `366` | Devis à taxe |
| `702` | Signataire du contact (pour les signatures électroniques) |
| `733` | Devis à panier |
| `408` | Devis à facture |
| `731` | Devis à commande |
| `398` | Devis à paiement |
| `304` | Devis à abonnement |
#### Tâche à objet
| ID DU TYPE | Type d'association |
| ---------- | ------------------- |
| `204` | Tâche à contact |
| `192` | Tâche à entreprise |
| `216` | Tâche à transaction |
| `230` | Tâche à ticket |
#### Communication (message SMS, WhatsApp ou LinkedIn) à objet
| ID DU TYPE | Type d'association |
| ---------- | --------------------------------------------------------------- |
| `81` | Communication (message SMS, WhatsApp ou LinkedIn) à contact |
| `87` | Communication (message SMS, WhatsApp ou LinkedIn) à entreprise |
| `85` | Communication (message SMS, WhatsApp ou LinkedIn) à transaction |
| `83` | Communication (message SMS, WhatsApp ou LinkedIn) à ticket |
### Commande à objet
| ID DU TYPE | Type d'association |
| ---------- | --------------------------- |
| `593` | Commande à panier |
| `507` | Commande à contact |
| `509` | Commande à entreprise |
| `512` | Commande à transaction |
| `362` | Commande à remise |
| `521` | Commande à code de remise |
| `408` | Commande à facture |
| `513` | Commande à ligne de produit |
| `523` | Commande à paiement |
| `730` | Commande à devis |
| `516` | Commande à abonnement |
| `726` | Commande à tâche |
| `525` | Commande à ticket |
### Panier à objet
| ID DU TYPE | Type d'association |
| ---------- | ------------------------- |
| `586` | Panier à contact |
| `588` | Panier à remise |
| `590` | Panier à ligne de produit |
| `592` | Panier à commande |
| `732` | Panier à devis |
| `728` | Panier à tâche |
| `594` | Panier à ticket |
## Associations v1 (hérité)
Si vous utilisez l’API d’associations v1, consultez le tableau ci-dessous pour plus d’informations sur les ID à utiliser lors de l’association de fiches d’informations.
| Type d'association | ID |
| ---------------------------------------- | --- |
| Contact à entreprise | 1 |
| Entreprise à contact (par défaut) | 2 |
| Entreprise à contact (tous les libellés) | 280 |
| Transaction à contact | 3 |
| Contact à transaction | 4 |
| Transaction à entreprise | 5 |
| Entreprise à transaction | 6 |
| Entreprise à interaction | 7 |
| Interaction à entreprise | 8 |
| Contact à interaction | 9 |
| Interaction à contact | 10 |
| Transaction à interaction | 11 |
| Interaction à transaction | 12 |
| Entreprise parent à entreprise enfant | 13 |
| Entreprise enfant à entreprise parent | 14 |
| Contact à ticket | 15 |
| Ticket à contact | 16 |
| Ticket à interaction | 17 |
| Interaction à ticket | 18 |
| Transaction à ligne de produit | 19 |
| Ligne de produit à transaction | 20 |
| Entreprise à ticket | 25 |
| Ticket à entreprise | 26 |
| Transaction à ticket | 27 |
| Ticket à transaction | 28 |