> ## 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 | Contacts

> Les fiches d'informations de contact stockent des informations sur des personnes. Les points de terminaison des contacts vous permettent de gérer ces données et de les synchroniser entre HubSpot et d'autres systèmes.

> **[Run in Postman](https://app.getpostman.com/run-collection/dd75d149eaa15806754f)**

> **Exigences de portée**

# Contacts

Dans HubSpot, les contacts stockent des informations sur les personnes qui interagissent avec votre entreprise. Les points de terminaison des contacts vous permettent de créer et de gérer des fiches d'informations de contact ainsi que de synchroniser des données de contact entre HubSpot et d'autres systèmes.

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](https://developers.hubspot.fr/docs/guides/crm/understanding-the-crm). Pour plus d'informations générales sur les objets et les fiches d'informations dans HubSpot, [découvrez comment gérer votre base de données CRM](http://knowledge.hubspot.com/contacts-user-guide).

## Créer des contacts

Pour créer de nouveaux contacts, effectuez une requête `POST` à `/crm/v3/objects/contacts`.

Dans votre requête, incluez les données de votre contact dans un objet de propriétés. Vous pouvez également ajouter un objet d'association pour associer votre nouveau contact à des fiches d'informations existantes (par exemple : des entreprises ou des transactions) ou à des activités (par exemple : des réunions ou des notes).

### Propriétés

Les détails du contact sont stockés dans des propriétés de contact. Il existe des [propriétés de contact HubSpot par défaut](https://knowledge.hubspot.com/fr/properties/hubspots-default-contact-properties), mais vous pouvez également créer des [propriétés personnalisées](https://knowledge.hubspot.com/fr/properties/create-and-edit-properties).

Lorsque vous créez un nouveau contact, vous devez inclure au moins une des propriétés suivantes dans votre requête : `email`, `firstname` ou `lastname`. Il est recommandé de toujours inclure `email`, car les adresses e-mail constituent le [principal identifiant unique](https://knowledge.hubspot.com/fr/records/deduplication-of-records#automatic-deduplication-in-hubspot) pour éviter les contacts en double dans HubSpot.

Pour afficher toutes les propriétés disponibles, vous pouvez récupérer une liste des contacts de votre compte en effectuant une requête `GET` à `/crm/v3/properties/contacts`. Découvrez-en davantage sur l'[API des propriétés](https://developers.hubspot.fr/docs/api-reference/crm-properties-v3/guide.md).

> [!WARNING]
>
> ### Remarque :
>
> Si vous avez inclus `lifecyclestage` dans votre requête, les valeurs doivent faire référence au nom interne de la phase du cycle de vie. Les noms internes des phases par défaut sont des valeurs textes et ne changent pas, même si vous modifiez le [libellé](https://knowledge.hubspot.com/fr/properties/create-and-edit-properties) de la phase (par exemple : `subscriber` ou `marketingqualifiedlead`). Les noms internes des [phases personnalisées](https://knowledge.hubspot.com/fr/object-settings/create-and-customize-lifecycle-stages) sont des valeurs numériques. Vous pouvez trouver l'ID interne d'une phase dans vos [paramètres de phase du cycle de vie](https://knowledge.hubspot.com/fr/object-settings/create-and-customize-lifecycle-stages)ou en récupérant la propriété de phase du cycle de vie via l'API.

Par exemple, pour créer un nouveau contact, votre requête peut ressembler à ce qui suit :

**JSON**

```json theme={null}
///Example request body
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+18884827768",
    "company": "HubSpot",
    "website": "hubspot.com",
    "lifecyclestage": "marketingqualifiedlead"
  }
}
```

### Associations

Lorsque vous créez un nouveau contact, vous pouvez également associer le contact à des [fiches d'informations](https://knowledge.hubspot.com/fr/records/associate-records) ou [activités](https://knowledge.hubspot.com/fr/records/associate-activities-with-records) existantes en incluant un objet d'associations. Par exemple, pour associer un nouveau contact à une entreprise et une adresse e-mail existantes, votre requête ressemblerait à ce qui suit :

**JSON**

```json theme={null}
///Example request body
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+18884827768",
    "company": "HubSpot",
    "website": "hubspot.com",
    "lifecyclestage": "marketingqualifiedlead"
  },
  "associations": [
    {
      "to": {
        "id": 123456
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 279
        }
      ]
    },
    {
      "to": {
        "id": 556677
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 197
        }
      ]
    }
  ]
}
```

Dans l'objet d'association, vous devez ajouter les éléments suivants :

| Paramètre | Description |
| - | - |
| `to` | La fiche d'informations ou l'activité à laquelle vous souhaitez associer le contact, en fonction de sa valeur `id` unique. |
| `types` | Le type d'association entre le contact et la fiche d'informations/l'activité. Inclut `associationCategory` et `associationTypeId`. Les ID de types d'association par défaut sont répertoriés [ici](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values), ou vous pouvez récupérer la valeur des types d'associations personnalisés (c'est-à-dire les libellés) via l'[API des associations](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md#retrieve-association-types). |

## Récupérer des contacts par ID de fiche d'informations, e-mail ou propriété de valeur unique personnalisée

Vous pouvez récupérer des contacts individuellement ou par lots.

* Pour récupérer un contact individuel, effectuez une requête `GET` à `/crm/v3/objects/contacts/{contactId} or` `/crm/v3/objects/contacts/{email}?idProperty=email`.
* Pour demander une liste de tous les contacts, effectuez une requête `GET` à `/crm/v3/objects/contacts`.

Pour ces points de terminaison, vous pouvez inclure les paramètres suivants dans l'URL de la requête :

| Paramètre | Description |
| - | - |
| `properties` | Une liste séparée par des virgules des propriétés à renvoyer dans la réponse. Si le contact demandé n'a pas de valeur pour une propriété, il n'apparaîtra pas dans la réponse. |
| `propertiesWithHistory` | Une liste séparée par des virgules des propriétés actuelles et historiques à renvoyer dans la réponse. Si le contact demandé n'a pas de valeur pour une propriété, il n'apparaîtra pas dans la réponse. |
| `associations` | Une liste séparée par des virgules des objets pour lesquels récupérer les ID associés. Les associations spécifiées qui n'existent pas ne seront pas renvoyées dans la réponse. Découvrez-en davantage sur l'[API des associations.](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md) |

* Pour récupérer un lot de contacts spécifiques par ID de fiche d'informations, adresse e-mail ou selon une [propriété d'identifiant unique personnalisée](https://developers.hubspot.fr/docs/api-reference/crm-properties-v3/guide.md#create-unique-identifier-properties), effectuez une requête `POST` à `crm/v3/objects/contacts/batch/read`. Le point de terminaison du lot ne peut pas récupérer les associations. Découvrez comment lire par lots les associations avec l'API [des associations](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md).

Pour le point de terminaison de lecture par lot, vous pouvez utiliser le paramètre `idProperty` facultatif pour récupérer les contacts par `email` ou en fonction d'une [propriété d'identifiant unique](https://developers.hubspot.fr/docs/api-reference/crm-properties-v3/guide.md#create-unique-identifier-properties) personnalisée. Par défaut, les valeurs d'`id` dans la requête font référence à l'ID de fiche d'informations (`hs_object_id`), de sorte que le paramètre `idProperty` n'est pas requis lors de la récupération par ID de fiche d'informations. Si vous utilisez `email` ou une propriété de valeur unique personnalisée pour récupérer des contacts, vous devez inclure le paramètre `idProperty`.

Par exemple, pour récupérer un lot de contacts en fonction de valeurs d'ID de fiche d'informations, votre requête peut ressembler à ce qui suit (valeurs actuelles uniquement, ou valeurs actuelles et historiques) :

```json theme={null}
{
  "properties": ["email", "lifecyclestage", "jobtitle"],
  "inputs": [
    {
      "id": "1234567"
    },
    {
      "id": "987456"
    }
  ]
}
```

```json theme={null}
{
  "propertiesWithHistory": ["lifecyclestage", "hs_lead_status"],
  "inputs": [
    {
      "id": "1234567"
    },
    {
      "id": "987456"
    }
  ]
}
```

Pour récupérer des contacts en fonction d'une adresse e-mail ou d'un identifiant unique personnalisé (par exemple, un numéro d'identification client unique pour votre entreprise), votre requête ressemblerait à ce qui suit :

```json theme={null}
{
  "properties": ["email", "lifecyclestage", "jobtitle"],
  "idProperty": "email",
  "inputs": [
    {
      "id": "lgilmore@thedragonfly.com"
    },
    {
      "id": "sstjames@thedragonfly.com"
    }
  ]
}
```

```json theme={null}
{
  "properties": ["email", "lifecyclestage", "jobtitle"],
  "idProperty": "internalcustomerid",
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}
```

## Mettre à jour des contacts

Vous pouvez mettre à jour des contacts individuellement ou par lots.

Pour mettre à jour des contacts individuels, vous pouvez utiliser l'ID de fiche d'informations (`id`) ou l'adresse e-mail du contact (`email`).

* Pour mettre à jour un contact individuel avec son ID de fiche d'informations, effectuez une requête `PATCH` à `/crm/v3/objects/contacts/{contactId}` et incluez les données que vous souhaitez mettre à jour.
* Pour mettre à jour un contact individuel avec son ID de fiche d'informations, effectuez une requête `PATCH` à `/crm/v3/objects/contacts/{email}?idProperty=email` et incluez les données que vous souhaitez mettre à jour.

Par exemple :

```json theme={null}
{
  "properties": {
    "favorite_food": "burger",
    "jobtitle": "Manager",
    "lifecyclestage": "Customer"
  }
}
```

> [!WARNING]
>
> ### Remarque :
>
> Si vous mettez à jour la propriété `lifecyclestage`, vous ne pouvez qu'avancer la valeur dans l'ordre des étapes. Pour rétrograder la phase du cycle de vie, vous devrez d'abord effacer la valeur de phase du cycle de vie existante de la fiche d'informations. La valeur peut être [effacée manuellement](https://knowledge.hubspot.com/fr/records/update-a-property-value-for-a-record), ou automatiquement via un [workflow](https://knowledge.hubspot.com/fr/records/change-record-lifecycle-stages-in-bulk) ou une intégration qui synchronise les données de contact.

Pour mettre à jour des contacts par lots, vous pouvez utiliser les valeurs d'ID de fiche d'informations des contacts (`id`). Pour mettre à jour plusieurs contacts, effectuez une requête `POST` à `/crm/v3/objects/contacts/batch/update`. Dans le corps de votre requête, incluez l'ID de fiche d'informations de chaque contact comme `id` et incluez les propriétés que vous souhaitez mettre à jour.

Par exemple :

```json theme={null}
{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "favorite_food": "burger"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "favorite_food": "Donut"
      }
    }
  ]
}
```

## Insérer des contacts

Vous pouvez également créer et mettre à jour des contacts par lots en même temps en utilisant le point de terminaison upsert. Pour ce point de terminaison, vous pouvez utiliser `email` ou une [propriété d'identifiant unique personnalisée](https://developers.hubspot.fr/docs/api-reference/crm-properties-v3/guide.md#create-unique-identifier-properties). À la suite de la requête, si les contacts existent déjà, ils seront mis à jour. S'ils n'existent pas, ils seront créés.

Pour insérer des contacts, effectuez une requête `POST` à `/crm/v3/objects/contacts/batch/upsert`. Dans le corps de votre requête, incluez le paramètre `idProperty` pour déterminer si vous utilisez `email` ou une propriété d'identifiant unique personnalisée. Incluez la valeur de cette propriété en tant qu'`id` et ajoutez les autres propriétés que vous souhaitez définir ou mettre à jour.

> [!WARNING]
>
> ### Remarque :
>
> Les mises à jour partielles ne sont pas prises en charge lors de l'utilisation de `email` comme `idProperty` pour les contacts. Pour réaliser un upsert partiel, utilisez plutôt une propriété d'identifiant unique personnalisé comme `idProperty`.

Par exemple, votre requête pourrait ressembler à ce qui suit :

```json theme={null}
{
  "inputs": [
    {
      "properties": {
        "phone": "+18884827768"
      },
      "id": "test@test.com",
      "idProperty": "email"
    },
    {
      "properties": {
        "phone": "+18888888888"
      },
      "id": "example@hubspot.com",
      "idProperty": "email"
    }
  ]
}
```

## Associer des contacts existants à des fiches d'informations ou activités

Pour associer un contact à d'autres fiches d'informations de CRM ou à une activité, effectuez une requête `PUT` à `/crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`.

> [!NOTE]
>
> Pour récupérer la valeur `associationTypeId`, reportez-vous à [cette liste](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values) de valeurs par défaut ou effectuez une requête `GET` à `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels`.

Découvrez-en davantage sur l'[API des associations.](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md)

### Supprimer une association

Pour supprimer une association entre un contact et une fiche d'informations ou une activité, effectuez une requête `DELETE` à l'URL suivante : `/crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`

## Épingler une activité à une fiche d'informations d'un contact

Vous pouvez [épingler une activité](https://knowledge.hubspot.com/fr/records/pin-an-activity-on-a-record) à une fiche d'informations de contact en incluant le champ `hs_pinned_engagement_id` dans votre requête. Dans le champ, incluez l'`id` de l'activité à épingler, qui peut être récupéré via les [API d'engagement](https://developers.hubspot.fr/docs/api-reference/overview.md). Vous pouvez épingler une activité par fiche d'informations, et l'activité doit déjà être associée au contact avant l'épinglage.

Pour définir ou mettre à jour l'activité épinglée d'un contact, votre requête peut ressembler à :

```json theme={null}
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
```

Vous pouvez également créer un contact, l'associer à une activité existante et épingler l'activité dans la même requête. Par exemple :

```json theme={null}
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+18884827768",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 201
        }
      ]
    }
  ]
}
```

## Supprimer des contacts

Vous pouvez supprimer des contacts individuellement ou par lots, ce qui placera le contact dans la corbeille dans HubSpot. Vous pourrez ensuite [restaurer la transaction dans HubSpot](https://knowledge.hubspot.com/fr/records/restore-deleted-records).

Pour supprimer un contact individuel avec son ID, effectuez une requête `DELETE` à `/crm/v3/objects/contacts/{contactId}`.

Pour en savoir plus sur la suppression de contacts par lots, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-contacts-v3/guide.md).

## E-mails supplémentaires

Les adresses e-mail additionnelles sont utilisées lorsqu'un contact a plus d'une adresse e-mail. Elles peuvent être ajoutées [manuellement sur une fiche d'informations de contact dans HubSpot](https://knowledge.hubspot.com/fr/records/add-multiple-email-addresses-to-a-contact) ou automatiquement après une [fusion de contact](https://knowledge.hubspot.com/fr/records/merge-records#contact-merge-exceptions). Les e-mails supplémentaires sont toujours des identifiants uniques pour les contacts, de sorte que plusieurs contacts ne peuvent pas avoir les mêmes adresses e-mail additionnelles.

Pour afficher les e-mails additionnelles pour les contacts, lorsque vous récupérez tous les contacts ou des contacts individuels, incluez le paramètre `properties` avec les propriétés `email` et `hs_additional_emails`. L'adresse e-mail principale d'un contact sera affichée dans le champ `email` et les adresses e-mail supplémentaires seront affichées dans le champ `hs_additional_emails`.

## Limites d'utilisation

Les opérations par lot sont limitées à 100 fiches d'informations à la fois. Par exemple, vous ne pouvez pas mettre à jour par lots plus de 100 contacts dans une requête. Il existe également des limites pour les [contacts et les soumissions de formulaires](https://developers.hubspot.fr/docs/index.md#limits_contacts).