Contacts

PrésentationPoints de terminaison

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. 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.

Créer des contacts

Pour créer de nouveaux contacts, effectuez une demande POST à /crm/v3/objects/contacts.

Dans votre demande, 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, mais vous pouvez également créer des propriétés personnalisées.

Lorsque vous créez un nouveau contact, vous devez inclure au moins une des propriétés suivantes dans votre demande : email, firstname ou lastname. Il est recommandé de toujours inclure email, car les adresses e-mail constituent le principal identifiant unique pour éviter les contacts en double dans HubSpot.

Pour afficher toutes les propriétés disponibles, vous pouvez récupérer une liste des propriétés de contact de votre compte en effectuant une demande GET à /crm/v3/properties/contacts. Découvrez-en davantage sur l'API des propriétés.

Remarque : Si vous avez inclus lifecyclestage dans votre demande, 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 textuelles et ne changent pas, même si vous modifiez le libellé de la phase (par exemple, subscriber ou marketingqualifiedlead). Les noms internes des phases personnalisées sont des valeurs numériques. Vous pouvez trouver l'ID interne d'une phase dans vos paramètres de phase du cycle de vie 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 demande peut ressembler à ce qui suit :

///Example request body { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "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 ou activités existantes. Dans l'objet d'association, ajoutez les champs suivants :

Use this table to describe parameters / fields
ParameterDescription
toObjectId

L'ID de la fiche d'informations ou de l'activité à laquelle vous souhaitez associer le contact.

associationTypeId

Un identifiant unique pour indiquer le type d'association entre le contact et l'autre objet ou activité. Les types d'association par défaut sont répertoriés ici, ou vous pouvez récupérer la valeur en effectuant une demande GET à /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. Découvrez-en davantage sur l'API des associations.

Vous pouvez également inclure le champ label pour attribuer un libellé d'association défini qui décrit l'association. Découvrez-en davantage sur l'association de fiches d'informations via l'API des associations.

Par exemple, pour associer un nouveau contact à une entreprise et une adresse e-mail existantes, votre demande ressemblerait à ce qui suit :

///Example request body { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "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 } ] }] }

Récupérer des contacts

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

  • Pour récupérer un contact individuel, effectuez une demande GET à /crm/v3/objects/contacts/{contactId}. 
  • Pour demander une liste de tous les contacts, effectuez une demande GET à /crm/v3/objects/contacts.

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

Use this table to describe parameters / fields
ParameterDescription
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.
  • 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, effectuez une demande POST à crm/v3/objects/companies/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.
Pour le point de terminaison de lecture par lot, vous pouvez utiliser le paramètre idProperty facultatif pour récupérer les contacts par e-mail ou en fonction d'une propriété d'identifiant unique personnalisée. Par défaut, les valeurs d'identifiant dans la demande 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 une adresse e-mail 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 demande peut ressembler à ce qui suit (valeurs actuelles uniquement, ou valeurs actuelles et historiques) :

///Example request body with record ID (current values) { "properties": [ "email", "lifecyclestage", "jobtitle" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }
///Example request body with record ID (current and historical values) { "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 demande ressemblerait à ce qui suit :

///Example request body with email { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "email", "inputs": [ { "id": "lgilmore@thedragonfly.com" }, { "id": "sstjames@thedragonfly.com" } ] }
///Example request body with a unique value property { "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 des contacts existants, l'adresse e-mail et la fiche d'informations sont des valeurs uniques. Vous pouvez donc utiliser id ou email pour mettre à jour le contact via l'API.

Pour mettre à jour un contact individuel avec son ID de contact, effectuez une demande PATCH à /crm/v3/objects/contacts/{contactId} et incluez les données que vous souhaitez mettre à jour.

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

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

Pour récupérer la valeur associationTypeId, reportez-vous à cette liste de valeurs par défaut ou effectuez une demande GET à/crm/v4/associations/{fromObjectType}/{toObjectType}/labels. 

Découvrez-en davantage sur l'API des associations.

Supprimer une association

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

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

You can pin an activity on a contact record by including the hs_pinned_engagement_id field in your request. In the field, include the id of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the contact prior to pinning.

To set or update a contact's pinned activity, your request could look like:

///Example request body PATCH /crm/v3/objects/contacts/{contactId} { "properties": { "hs_pinned_engagement_id": 123456789 } }

You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example:

///Example request body POST /crm/v3/objects/contacts { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "hs_pinned_engagement_id": 123456789 }, "associations": [ { "to": { "id": 123456789 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 201 }] }] }

Delete 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.

Pour supprimer un contact avec son ID, effectuez une demande DELETE à /crm/v3/objects/contacts/{contactId}.

Pour en savoir plus sur la suppression de contacts par lots, cliquez sur l'onglet Points de terminaison en haut de cet article.

Limites d'utilisation

Batch operations for creating, updating, and archiving are limited to batches of 100. There are also limits for contacts and form submissions.

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.