API de CRM | cartes CRM

Dernière modification : 28 août 2025

Run in Postman

Dans une application publique, vous pouvez créer des cartes CRM personnalisées pour afficher des informations provenant d’autres systèmes sur les fiches d’informations de contacts, d’entreprises, de transactions et de tickets HubSpot. Chaque application peut inclure jusqu’à 25 cartes CRM.

À compter du 16 juin 2025, les fonctionnalités des cartes CRM classiques décrites dans cet article ne seront plus prises en charge et seront officiellement obsolètes le 31 octobre 2026. Découvrez-en davantage sur cette annonce dans le journal des modifications des développeurs HubSpot.Les cartes CRM classiques sont différentes des cartes d’application que vous pouvez créer en tant qu’extensions d’interface utilisateur avec des projets. Les nouvelles cartes d’application offrent plus de flexibilité, de personnalisation et d’interactivité en utilisant un ensemble d’outils plus modernes, basés sur React. Si votre application comprend actuellement une carte CRM classique, découvrez comment la migrer vers le cadre de projets afin d’utiliser des cartes d’application plus récentes.

Exemple de cas d’utilisation : vous créez une intégration pour le marketplace des applications pour votre logiciel de suivi des bogues. Vous voulez faire apparaître les bugs suivis sur les fiches d’informations de contacts afin que les conseillers du support puissent les référencer lorsque vous travaillez avec les clients. Votre application peut définir une carte personnalisée qui affiche ces informations sur la fiche d’informations de contact HubSpot.

Les cartes peuvent être définies dans les paramètres de fonctionnalité de votre application. Une fois que l’application est installée et qu’un utilisateur consulte les fiches d’informations du CRM cibles, HubSpot effectue une requête sortante à l’application, récupère les données pertinentes et les affiche dans une carte sur la page de la fiche d’informations. Les applications peuvent également spécifier des actions personnalisées que l’utilisateur peut effectuer en fonction de ces informations. Par exemple, votre application peut inclure une action qui ouvre une fenêtre glissante pour afficher sa propre interface utilisateur dans HubSpot.

Exigences des domaines

Pour créer des cartes CRM personnalisées, votre application doit demander les domaines OAuth requis pour modifier les fiches d’informations de CRM dans lesquelles votre carte apparaîtra. Par exemple, pour qu’une carte CRM apparaisse sur les fiches d’informations de contacts, l’application doit avoir les paramètres crm.objects.contacts.read et crm.objects.contacts.write. Si vous devez supprimer ultérieurement les paramètres d’objets CRM de votre application, vous devrez d’abord supprimer toutes les cartes existantes pour ces types d’objets. Consultez la documentation OAuth pour plus de détails sur les domaines et la configuration de l’URL d’autorisation pour votre application.

Créer une carte CRM

Vous pouvez créer des cartes CRM pour votre application via l’API ou en modifiant votre application dans votre compte de développeur. Pour en savoir plus sur la configuration d’une carte via l’API, consultez la documentation de référence. Pour créer une carte CRM à l’aide de l’interface utilisateur de HubSpot :

Dans votre compte de développeur de HubSpot, accédez à Apps dans la navigation principale.
Sélectionnez l’application à laquelle vous souhaitez ajouter une carte.
Dans le menu latéral de gauche, sélectionnez Cartes CRM.
Cliquez sur Créer une carte CRM dans l’angle supérieur droit.

Découvrez ci-dessous les options de configuration dans chaque onglet.

Les extensions d’interface utilisateur construites à l’aide de projets de développement offrent des moyens plus flexibles d’afficher des données et permettent l’interaction de l’utilisateur, y compris l’affichage de contenu externe dans des cadres. Si l’utilisation d’une application privée est possible pour votre intégration, consultez le guide de démarrage rapide des extensions d’interface utilisateur pour commencer, ou consultez les exemples de projets HubSpot pour voir des exemples de ce qui est possible.

Demande de données

Lorsqu’un utilisateur HubSpot affiche une fiche d’informations CRM dans laquelle la carte CRM est activée, HubSpot formulera une requête de récupération de données à l’intégration. Cette requête est faite à l’URL cible spécifiée, qui comprend un ensemble de paramètres de requête par défaut, ainsi que des paramètres supplémentaires contenant des données de propriété telles que spécifiées dans les paramètres de la carte.

private-app-create-crm-card-data-request-tab

Dans le champ URL de récupération des données, saisissez l’URL à partir de laquelle vous allez récupérer les données. Dans l’API, cette URL est ajoutée au champ targetUrl.
Dans la section Types de fiches d’informations cibles, cliquez pour activer les options afin de sélectionner les fiches d’informations CRM dans lesquelles la carte apparaîtra. Ensuite, utilisez les menus déroulants Propriétés envoyées par HubSpot pour sélectionner les propriétés HubSpot qui seront incluses en tant que paramètres de requête dans l’URL de la requête. Dans l’API, chaque type de fiche d’informations et ses propriétés correspondantes sont ajoutés en tant qu’objets dans le tableau objectTypes.

{
  "title": "New CRM Card",
  "fetch": {
    "targetUrl": "https://www.example.com/demo-fetch",
    "objectTypes": [
      {
        "name": "contacts",
        "propertiesToSend": [
          "firstname",
          "email",
          "lastname"
        ]
      }
    ]
  }
...
}

Exemple de requête

La configuration ci-dessus entraînerait l’envoi par HubSpot de sa requête GET comme suit.

https://www.example.com/demo-fetch?userId=12345&userEmail=loggedinuser@hubspot.com&associatedObjectId=53701&associatedObjectType=CONTACT&portalId=987654&firstname=Tim&email=timrobinson@itysl.com&lastname=Robinson

Paramètre	Type	Description
`userId`	Défaut	L’ID de l’utilisateur HubSpot qui a chargé la fiche d’informations CRM.
`userEmail`	Défaut	L’adresse e-mail de l’utilisateur qui a chargé la fiche d’informations CRM.
`associatedObjectId`	Défaut	L’ID de la fiche d’informations CRM qui a été chargée.
`associatedObjectType`	Défaut	Le type de fiche d’informations CRM qui a été chargée (par exemple, contact, entreprise, transaction).
`portalId`	Défaut	L’ID du compte HubSpot dans lequel la fiche d’informations CRM a été chargée.
`firstname`	Personnalisé	Le prénom du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l’application) et le tableau `propertiesToSend` (API).
`email`	Personnalisé	L’adresse e-mail du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l’application) et le tableau `propertiesToSend` (API).
`lastname`	Personnalisé	Le nom de famille du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l’application) et le tableau `propertiesToSend` (API).

Remarque :

Une connexion doit être établie dans les 3 secondes et les requêtes expireront au bout de 5 secondes.

Exemple de réponse

Vous trouverez ci-dessous un exemple de réponse que l’intégrateur pourrait fournir à la requête ci-dessus.

{
  "results": [
    {
      "objectId": 245,
      "title": "API-22: APIs working too fast",
      "link": "http://example.com/1",
      "created": "2016-09-15",
      "priority": "HIGH",
      "project": "API",
      "description": "Customer reported that the APIs are just running too fast. This is causing a problem in that they're so happy.",
      "reporter_type": "Account Manager",
      "status": "In Progress",
      "ticket_type": "Bug",
      "updated": "2016-09-28",
      "actions": [
        {
          "type": "IFRAME",
          "width": 890,
          "height": 748,
          "uri": "https://example.com/edit-iframe-contents",
          "label": "Edit",
          "associatedObjectProperties": []
        },
        {
          "type": "IFRAME",
          "width": 890,
          "height": 748,
          "uri": "https://example.com/reassign-iframe-contents",
          "label": "Reassign",
          "associatedObjectProperties": []
        },
        {
          "type": "ACTION_HOOK",
          "httpMethod": "PUT",
          "associatedObjectProperties": [],
          "uri": "https://example.com/tickets/245/resolve",
          "label": "Resolve"
        },
        {
          "type": "CONFIRMATION_ACTION_HOOK",
          "confirmationMessage": "Are you sure you want to delete this ticket?",
          "confirmButtonText": "Yes",
          "cancelButtonText": "No",
          "httpMethod": "DELETE",
          "associatedObjectProperties": ["protected_account"],
          "uri": "https://example.com/tickets/245",
          "label": "Delete"
        }
      ]
    },
    {
      "objectId": 988,
      "title": "API-54: Question about bulk APIs",
      "link": "http://example.com/2",
      "created": "2016-08-04",
      "priority": "HIGH",
      "project": "API",
      "reported_by": "ksmith@hubspot.com",
      "description": "Customer is not able to find documentation about our bulk Contacts APIs.",
      "reporter_type": "Support Rep",
      "status": "Resolved",
      "ticket_type": "Bug",
      "updated": "2016-09-23",
      "properties": [
        {
          "label": "Resolved by",
          "dataType": "EMAIL",
          "value": "ijones@hubspot.com"
        },
        {
          "label": "Resolution type",
          "dataType": "STRING",
          "value": "Referred to documentation"
        },
        {
          "label": "Resolution impact",
          "dataType": "CURRENCY",
          "value": "94.34",
          "currencyCode": "GBP"
        }
      ],
      "actions": [
        {
          "type": "IFRAME",
          "width": 890,
          "height": 748,
          "uri": "https://example.com/edit-iframe-contents",
          "label": "Edit"
        },
        {
          "type": "CONFIRMATION_ACTION_HOOK",
          "confirmationMessage": "Are you sure you want to delete this ticket?",
          "confirmButtonText": "Yes",
          "cancelButtonText": "No",
          "httpMethod": "DELETE",
          "associatedObjectProperties": ["protected_account"],
          "uri": "https://example.com/tickets/245",
          "label": "Delete"
        }
      ]
    }
  ],
  "settingsAction": {
    "type": "IFRAME",
    "width": 890,
    "height": 748,
    "uri": "https://example.com/settings-iframe-contents",
    "label": "Settings"
  },
  "primaryAction": {
    "type": "IFRAME",
    "width": 890,
    "height": 748,
    "uri": "https://example.com/create-iframe-contents",
    "label": "Create Ticket"
  }
}

Propriété	Type	Description
`results`	Tableau	Un tableau comprenant jusqu’à 5 propriétés de carte valides. Si plusieurs propriétés de carte sont disponibles pour un objet de CRM spécifique, votre application peut rediriger vers celles-ci.
`objectId`	Nombre	Un ID unique pour cet objet.
`title`	Chaîne	Le titre de cet objet.
`link`	Chaîne	L’URL que l’utilisateur peut suivre pour obtenir plus de détails sur l’objet. Cette propriété est facultative, mais si aucun objet n’a de lien, vous devez fournir une valeur `null`.
`created`	Chaîne	Une propriété personnalisée, telle que définie dans les paramètres de la carte, qui indique la date de création de l’objet.
`priority`	Chaîne	Une propriété personnalisée, telle que définie dans les paramètres de la carte, qui indique le niveau de priorité du ticket externe.
`actions`	Tableau	Une liste des actions disponibles qu’un utilisateur peut effectuer pour cet objet.
`properties`	Propriétés	Une liste des propriétés personnalisées qui ne sont pas définies dans les paramètres de la carte. Vous pouvez utiliser cette liste pour afficher les propriétés uniques d’un objet spécifique. Ces propriétés seront affichées dans l’ordre dans lequel elles sont fournies, mais après les propriétés définies dans les paramètres de la carte.
`settingsAction`	Objet	Une action d’iframe qui permet aux utilisateurs de mettre à jour les paramètres de l’application.
`primaryAction`	Objet	L’action principale pour un type de fiche d’informations, généralement une action de création.
`secondaryActions`	Tableau	Une liste d’actions affichées sur la carte.

Signatures de requête

Pour s’assurer que les requêtes proviennent bien de HubSpot, l’en-tête de requête suivant est inclus. Cet en-tête contiendra un hachage du secret de l’application pour votre application ainsi que les détails de la requête. X-HubSpot-Signature: <some base64 string> Pour vérifier cette signature, effectuez les étapes suivantes :

Créez une chaîne qui regroupe les éléments suivants : <app secret> + <HTTP method> + <URL> + <request body> (if present).
Créez un hachage SHA-256 de la chaîne résultante.
Comparer la valeur de hachage à la signature. Si elle est égale, la requête a été validée. Si elle ne correspond pas, cette requête peut avoir été modifiée en transit ou quelqu’un peut usurper les requêtes à votre point de terminaison.

Découvrez-en davantage sur la validation des requêtes de HubSpot.

Propriétés de la carte

Dans l’onglet Propriétés de la carte, définissez toutes les propriétés personnalisées que vous souhaitez que HubSpot affiche sur la carte CRM. Une fois définie, l’intégration peut remplir ces propriétés en les incluant dans sa réponse.

Cliquez sur Ajouter une propriété pour ajouter une nouvelle propriété à afficher sur la carte. La charge utile que vous fournissez en réponse à l’appel d’extraction de données doit contenir des valeurs pour toutes ces propriétés.
Dans le panneau de droite, définissez le nom unique, le libellé d’affichage et le type de données de la propriété. Vous pouvez choisir parmi les types suivants : Devise, Date, Datetime, E-mail, Lien, Numérique, Statut et Chaîne. Découvrez-en davantage sur l’utilisation des types de propriétés d’extension.
Cliquez sur Ajouter pour enregistrer la propriété.

private-app-create-crm-card-card-properties-tab

Lorsque HubSpot envoie sa requête de données, l’intégration peut fournir des valeurs pour ces propriétés dans sa réponse ainsi que d’autres valeurs dans chaque objet dans la propriété results. Outre les propriétés configurées dans cet onglet, l’intégration peut également inclure ses propres propriétés personnalisées sans avoir besoin de les définir dans les paramètres de la carte. Par exemple, dans la réponse ci-dessous, les paramètres created et priority sont tous deux définis dans l’onglet Propriétés de la carte, tandis que le tableau properties envoie ses propres définitions et valeurs de propriétés. Ces propriétés spécifiques à l’objet doivent être définies par objet.

{
  "objectId": 988,
  "title": "API-54: Question about bulk APIs",
  "link": "http://example.com/2",
  "created": "2016-08-04",
  "priority": "HIGH",
  "properties": [
    {
      "label": "Resolved by",
      "dataType": "EMAIL",
      "value": "ijones@hubspot.com"
    },
    {
      "label": "Resolution type",
      "dataType": "STRING",
      "value": "Referred to documentation"
    },
    {
      "label": "Resolution impact",
      "dataType": "CURRENCY",
      "value": "94.34",
      "currencyCode": "GBP"
    }
  ],
  "actions": [
   ...
  ]
}

Lors de l’envoi de propriétés personnalisées, le champ dataType de chaque propriété peut être défini sur l’un des éléments suivants : CURRENCY, DATE, DATETIME, EMAIL, LINK, NUMERIC, STATUS, STRING. Selon le type de propriété, l’intégration peut devoir fournir des champs supplémentaires. Découvrez-en davantage ci-dessous sur chaque type de propriété.

Propriétés de devise

Les propriétés CURRENCY doivent inclure un paramètre currencyCode, qui doit être un code ISO 4217 valide. Cela garantira que l’utilisateur voit le symbole de devise et la mise en forme des chiffres corrects.

{
  "results": [
    {
      "properties": [
        {
          "label": "Resolution impact",
          "dataType": "CURRENCY",
          "value": "94.34",
          "currencyCode": "GBP"
        }
      ]
    }
  ]
}

Propriétés de date

Les propriétés DATE doivent être au format aaaa-mm-jj. Ces propriétés seront affichées dans un format correspondant aux paramètres régionaux de l’utilisateur. Si vous devez inclure un horodatage, vous devez plutôt utiliser une propriété DATETIME.

{
  "results": [
    {
      "properties": [
        {
          "label": "Date",
          "dataType": "DATE",
          "value": "2023-10-13"
        }
      ]
    }
  ]
}

Propriétés datetime

Les propriétés DATETIME indiquent une heure spécifique et doivent être fournies au format epoch en millisecondes. Ces propriétés seront affichées dans un format correspondant aux paramètres régionaux de l’utilisateur.

{
  "results": [
    {
      "properties": [
        {
          "label": "Timestamp",
          "dataType": "DATETIME",
          "value": "1697233678777"
        }
      ]
    }
  ]
}

Propriétés d’e-mail

Les propriétés EMAIL sont utilisées pour les valeurs qui contiennent une adresse e-mail. Ces propriétés s’affichent comme des liens mailto.

{
  "results": [
    {
      "properties": [
        {
          "label": "Email address",
          "dataType": "EMAIL",
          "value": "hobbes.baron@gmail.com"
        }
      ]
    }
  ]
}

Propriétés de lien

Les propriétés LINK affichent des liens hypertextes et s’ouvrent dans une nouvelle fenêtre. Vous pouvez spécifier un linkLabel, sinon l’URL elle-même sera affichée.

{
  "results": [
    {
      "properties": [
        {
          "label": "Link property",
          "dataType": "LINK",
          "value": "https://www.hubspot.com",
          "linkLabel": "Test link"
        }
      ]
    }
  ]
}

Propriétés numériques

Les propriétés NUMERIC affichent des chiffres.

{
  "results": [
    {
      "properties": [
        {
          "label": "Number",
          "dataType": "NUMERIC",
          "value": "123.45"
        }
      ]
    }
  ]
}

Propriétés de statut

Les propriétés STATUS s’affichent comme des indicateurs colorés. Pour définir une propriété de statut, l’intégration doit fournir un optionType qui décrit les statuts possibles. Les statuts sont les suivants

DEFAULT : Gris
SUCCESS : Vert
WARNING : Jaune
DANGER : Rouge
INFO : Bleu

{
  "results": [
    {
      "properties": [
        {
          "label": "Status",
          "dataType": "STATUS",
          "value": "Errors occurring",
          "optionType": "DANGER"
        }
      ]
    }
  ]
}

Propriétés de chaîne

Les propriétés STRING affichent du texte.

{
  "results": [
    {
      "properties": [
        {
          "label": "First name",
          "dataType": "STRING",
          "value": "Tim Robinson"
        }
      ]
    }
  ]
}

Actions personnalisées

Dans l’onglet Actions personnalisées, vous pouvez définir les URL de base qui seront demandées lorsqu’un utilisateur clique sur un bouton d’action. Vous pouvez inclure plusieurs URL d’action pour diverses actions dans votre carte CRM. Les actions de carte doivent appeler un point de terminaison spécifié dans cet onglet.

Private-app-create-crm-card-custom-actions-tab

Les hooks d’action et les requêtes de hooks de confirmation incluront un en-tête X-HubSpot-Signature pour vérifier la requête. Les requêtes d’action iframe n’incluront pas de signature de requête. Consultez les signatures de requête pour plus d’informations. Les URL d’action sont accessibles dans le champ uri d’une action. À l’instar de la requête de récupération de données, les hooks d’action incluront un ensemble par défaut de paramètres de requête. Vous pouvez inclure d’autres paramètres de requête en incluant un champ associatedObjectProperties dans l’action. La réponse variera en fonction du type d’action. Découvrez-en davantage ci-dessous sur les types d’actions.

Types d’actions

Actions iframe

Les actions IFRAME ouvrent une fenêtre modale contenant un iframe pointant sur l’URL fournie. Aucune signature de requête n’est envoyée lorsque l’iframe est ouvert à partir de l’interface utilisateur CRM. En effet, l’URL de l’iframe est renvoyée dans la requête de récupération de données d’origine et aucune autre requête de proxy n’est nécessaire.

{
  "type": "IFRAME",
  "width": 890,
  "height": 748,
  "uri": "https://example.com/iframe-contents",
  "label": "Edit",
  "associatedObjectProperties": ["some_crm_property"]
}

Lorsque l’utilisateur a terminé une action dans l’iframe, la fenêtre modale doit se fermer et rediriger l’utilisateur vers la fiche d’informations du CRM à partir de laquelle il a commencé. Pour fermer la fenêtre modale, l’intégration peut utiliser window.postMessage pour signaler au CRM que l’utilisateur a terminé. Les messages suivants sont acceptés :

{"action": "DONE"} : l’utilisateur a correctement finalisé l’action.
{"action": "CANCEL"} : l’utilisateur a annulé l’action.

window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Actions de hook d’action

Les actions ACTION_HOOK envoient une requête côté serveur à l’intégrateur. La seule interface utilisateur qu’un utilisateur voit pour cette action est un message de réussite ou d’erreur. Ce type d’action est utile pour des opérations simples qui ne nécessitent pas d’entrée supplémentaire de la part de l’utilisateur. Un en-tête X-HubSpot-Signature sera inclus dans la requête de vérification. En savoir plus sur les signatures de requête.

{
  "type": "ACTION_HOOK",
  "httpMethod": "POST",
  "uri": "https://example.com/action-hook",
  "label": "Example action",
  "associatedObjectProperties": ["some_crm_property"]
}

La propriété httpMethod peut être définie sur GET, POST, PUT, DELETE ou PATCH. Si vous utilisez la propriété GET ou DELETE, les valeurs associatedObjectProperties seront ajoutées à l’URL de la requête en tant que paramètres de requête. Dans le cas contraire, les propriétés seront envoyées dans le corps de la requête.

window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Actions de confirmation

Les actions CONFIRMATION_ACTION_HOOK ont un comportement identique à celui des actions ACTION_HOOK, à l’exception d’une boîte de dialogue de confirmation affichée pour l’utilisateur avant l’exécution de la requête côté serveur. Un en-tête X-HubSpot-Signature sera inclus dans la requête de vérification. En savoir plus sur les signatures de requête.

{
  "type": "CONFIRMATION_ACTION_HOOK",
  "httpMethod": "POST",
  "uri": "https://example.com/action-hook",
  "label": "Example action",
  "associatedObjectProperties": ["some_crm_property"],
  "confirmationMessage": "Are you sure you want to run example action?",
  "confirmButtonText": "Yes",
  "cancelButtonText": "No"
}

Supprimer une carte CRM

Une fois créée, vous pouvez supprimer une carte CRM à partir des paramètres de l’application :

Dans votre compte de développeur de HubSpot, accédez à Apps dans la navigation principale.
Cliquez sur le nom de l’application dont vous souhaitez supprimer une carte.
Dans le menu latéral de gauche, sélectionnez Cartes CRM.
Passez le curseur de la souris sur la carte, puis cliquez sur Supprimer.

delete-a-classic-crm-card-from-within-app-settings

Dans la boîte de dialogue, confirmez la suppression en cliquant sur Supprimer cette carte.

Analytics et événements

CRM

Run in Postman

​Exigences des domaines

​Créer une carte CRM

​Demande de données

​Exemple de requête

​Remarque :

​Exemple de réponse

​Signatures de requête

​Propriétés de la carte

​Propriétés de devise

​Propriétés de date

​Propriétés datetime

​Propriétés d’e-mail

​Propriétés de lien

​Propriétés numériques

​Propriétés de statut

​Propriétés de chaîne

​Actions personnalisées

​Types d’actions

​Actions iframe

​Actions de hook d’action

​Actions de confirmation

​Supprimer une carte CRM

Exigences des domaines

Créer une carte CRM

Demande de données

Exemple de requête

Remarque :

Exemple de réponse

Signatures de requête

Propriétés de la carte

Propriétés de devise

Propriétés de date

Propriétés datetime

Propriétés d’e-mail

Propriétés de lien

Propriétés numériques

Propriétés de statut

Propriétés de chaîne

Actions personnalisées

Types d’actions

Actions iframe

Actions de hook d’action

Actions de confirmation

Supprimer une carte CRM