HubSpot : référence technique

Objectif

Ceci est le complément technique à la documentation principale du connecteur HubSpot. Il couvre les internes de l'authentification, la référence complète des endpoints, les scopes, la pagination, le format de sortie et les limitations, tout ce qui est nécessaire pour intégrer le connecteur dans un pipeline de données.

Authentification

Méthodes prises en charge

Toutes les méthodes utilisent le même en-tête Bearer :

Authorization: Bearer {token}

Méthodes d'authentification obsolètes

Format des identifiants

{
  "token": "pat-eu1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Architecture

Le connecteur renvoie du JSON brut depuis l'API HubSpot. La platform prend le relais à partir de là. Elle détecte automatiquement le schéma à partir du payload JSON, aplatit les objets imbriqués en colonnes en notation pointée (converties en minuscules avec underscores), et stocke le résultat dans le lakehouse, interrogeable via Trino. Tout nouveau champ ajouté par HubSpot à un objet apparaît automatiquement à l'extraction suivante ; vous ne définissez aucun schéma, ne listez aucune colonne, et n'écrivez aucun code de transformation.

Le connecteur lui-même est responsable de l'authentification (Bearer token), du routage des endpoints, de la pagination (curseur ou décalage selon l'endpoint), et des nouvelles tentatives sur limite de débit.

Types d'objets CRM

27 objets standards

Le connecteur expose les 27 types d'objets CRM standards de HubSpot. Chacun est accessible via /crm/v3/objects/{object_type} (sauf owners, voir ci-dessous).

CRM principal

Interactions

E-commerce & ventes

Commerce

Commerce Hub

Sales Hub

Service & planification

Cas particulier : Owners

Owners utilise un endpoint dédié (GET /crm/v3/owners) au lieu de /crm/v3/objects/owners. Le connecteur gère cela automatiquement lorsque object_type=owners est sélectionné.

Référence des endpoints

crm_objects

Extrait des enregistrements de n'importe quel type d'objet CRM.

API : GET /crm/v3/objects/{object_type}?properties={props}&limit=100&after={cursor}

Pagination : basée sur un curseur (paging.next.after)

Sortie : JSON brut. Chaque enregistrement a id, createdAt, updatedAt, archived, et un dictionnaire properties imbriqué contenant toutes les valeurs de propriétés demandées.

Comportement des propriétés :

• Filtre vide : récupère TOUTES les propriétés via GET /crm/v3/properties/{type} d'abord, puis les demande toutes
• Avec filtre : demande uniquement les propriétés spécifiées
• HubSpot renvoie toutes les valeurs de propriétés sous forme de chaînes (même les nombres et les dates)

associations

Extrait les relations entre objets CRM.

API : POST /crm/v4/associations/{from_type}/{to_type}/batch/read

Pagination : basée sur un curseur sur les objets source, POST en lot pour la recherche d'associations (max 1000 ID par requête)

Sortie : JSON brut. Chaque résultat contient des objets from et to avec les ID et les métadonnées d'association.

association_definitions

Récupère les types d'association disponibles entre deux types d'objets.

API : GET /crm/v4/associations/{from_type}/{to_type}/labels

Pagination : aucune (GET unique)

Sortie : JSON brut, définitions des types d'association avec catégorie, ID de type, et libellé.

pipelines

Extrait les définitions de pipeline avec leurs étapes.

API : GET /crm/v3/pipelines/{pipeline_object_type}

Pagination : aucune (GET unique, renvoie tous les pipelines)

Sortie : JSON brut. Chaque pipeline contient id, label, displayOrder, createdAt, updatedAt, et un tableau stages imbriqué. La platform aplatit automatiquement les étapes en lignes séparées.

pipeline_audit

Journal d'audit pour un pipeline spécifique.

API : GET /crm/v3/pipelines/{object_type}/{pipeline_id}/audit

Pagination : aucune (GET unique)

Sortie : JSON brut, entrées d'audit telles que renvoyées par l'API.

properties_meta

Extrait le dictionnaire de données (schéma de propriétés) pour un type d'objet.

API : GET /crm/v3/properties/{property_object_type}

Pagination : aucune (GET unique)

Sortie : JSON brut. Chaque propriété a name, label, type, fieldType, groupName, description, et plus encore.

property_groups

Extrait les groupes de propriétés pour un type d'objet.

API : GET /crm/v3/properties/{property_object_type}/groups

Pagination : aucune (GET unique)

Sortie : JSON brut, définitions de groupes telles que renvoyées par l'API.

lists

Extrait les définitions de listes et de segments.

API : GET /crm/v3/lists

Pagination : basée sur un curseur

Sortie : JSON brut, définitions de listes telles que renvoyées par l'API.

list_memberships

Récupère les ID des enregistrements membres d'une liste spécifique.

API : GET /crm/v3/lists/{list_id}/memberships

Pagination : basée sur un curseur

Sortie : JSON brut, enregistrements d'adhésion tels que renvoyés par l'API.

marketing_emails

Extrait les définitions d'e-mails marketing avec leurs statistiques.

API : GET /marketing/v3/emails

Pagination : basée sur un curseur

Sortie : JSON brut, données de campagne e-mail avec des statistiques imbriquées, aplaties par la platform.

forms

Extrait les définitions de formulaires.

API : GET /marketing/v3/forms

Pagination : basée sur un curseur

Sortie : JSON brut, définitions de formulaires telles que renvoyées par l'API.

form_submissions

Extrait les soumissions pour un formulaire spécifique.

API : GET /form-integrations/v1/submissions/forms/{form_id}

Pagination : basée sur un décalage (API v1, utilise offset + hasMore, PAS basée sur un curseur)

Sortie : JSON brut, données de soumission telles que renvoyées par l'API.

conversations

Extrait les fils de conversation (chat, e-mail, bot).

API : GET /conversations/v3/conversations/threads

Pagination : basée sur un curseur

Sortie : JSON brut, données de fil telles que renvoyées par l'API.

Requiert : scope Conversations + plan HubSpot approprié

campaigns

Extrait les définitions de campagnes marketing.

API : GET /marketing/v3/campaigns

Pagination : basée sur un curseur

Sortie : JSON brut, données de campagne telles que renvoyées par l'API.

blog_posts

Extrait les articles de blog CMS.

API : GET /cms/v3/blogs/posts

Pagination : basée sur un curseur

Sortie : JSON brut, données d'article de blog (titre, contenu, auteur, date de publication, etc.).

site_pages

Extrait les pages de site web CMS.

API : GET /cms/v3/pages/site-pages

Pagination : basée sur un curseur

Sortie : JSON brut, données de page telles que renvoyées par l'API.

landing_pages

Extrait les pages d'atterrissage CMS.

API : GET /cms/v3/pages/landing-pages

Pagination : basée sur un curseur

Sortie : JSON brut, données de page telles que renvoyées par l'API.

workflows

Extrait les définitions de workflows d'automatisation.

API : GET /automation/v3/workflows

Pagination : aucune (GET unique, la clé de données est workflows, pas results)

Sortie : JSON brut, définitions de workflows telles que renvoyées par l'API.

sequences

Extrait les définitions de séquences commerciales.

API : GET /automation/v4/sequences

Pagination : basée sur un curseur

Sortie : JSON brut, données de séquence telles que renvoyées par l'API.

Requiert : Sales Hub Pro+

users

Extrait les utilisateurs du compte.

API : GET /settings/v3/users

Pagination : basée sur un curseur

Sortie : JSON brut, données utilisateur telles que renvoyées par l'API.

imports

Extrait l'historique des imports CRM.

API : GET /crm/v3/imports

Pagination : basée sur un curseur

Sortie : JSON brut, enregistrements d'import tels que renvoyés par l'API.

crm_schemas

Extrait les définitions de schéma d'objets personnalisés.

API : GET /crm/v3/schemas

Pagination : aucune (GET unique)

Sortie : JSON brut, définitions de schéma telles que renvoyées par l'API.

custom_events

Extrait les événements comportementaux pour un enregistrement CRM spécifique.

API : GET /events/v3/events?objectType={type}&objectId={id}

Pagination : basée sur un curseur (avec extra_params)

Sortie : JSON brut, données d'événement telles que renvoyées par l'API.

Requiert : Marketing Hub Enterprise

timeline_events

Extrait les modèles d'événements de timeline pour une application d'intégration.

API : GET /crm/v3/timeline/{app_id}/event-templates

Pagination : aucune (GET unique)

Sortie : JSON brut, données de modèle d'événement telles que renvoyées par l'API.

hubdb_tables

Extrait les définitions de tables HubDB.

API : GET /cms/v3/hubdb/tables

Pagination : basée sur un curseur

Sortie : JSON brut, définitions de tables telles que renvoyées par l'API.

Scopes par endpoint

Objets CRM

Autres endpoints

Pour les endpoints non listés ci-dessus (workflows, sequences, users, imports, crm_schemas, conversations, custom_events, hubdb_tables, timeline_events), consultez la référence des scopes de HubSpot pour le nom de scope faisant autorité.

Pagination

Le connecteur utilise trois stratégies de pagination selon l'endpoint :

Basée sur un curseur (la plupart des endpoints)

GET /crm/v3/objects/contacts?limit=100&after=NTI1Cg==

Réponse :

{
  "results": [...],
  "paging": {
    "next": { "after": "NTI1Cg==" }
  }
}

Lorsque paging.next.after est absent, toutes les données ont été récupérées.

Basée sur un décalage (soumissions de formulaires uniquement)

GET /form-integrations/v1/submissions/forms/{id}?limit=50&offset=0

Réponse :

{
  "results": [...],
  "hasMore": true,
  "offset": 50
}

Lorsque hasMore est faux, toutes les données ont été récupérées.

Aucune pagination (GET unique)

Certains endpoints renvoient toutes les données en une seule réponse : pipelines, pipeline_audit, properties_meta, property_groups, association_definitions, workflows, timeline_events, crm_schemas.

Limites de débit

Limites par plan

Consultez la documentation officielle de HubSpot sur les limites de débit pour les limites actuelles. Les limites varient selon le plan et l'endpoint de l'API.

Gestion des limites de débit

Le connecteur gère automatiquement les réponses 429 Too Many Requests :

1. Lit l'en-tête Retry-After (secondes à attendre)
2. Se rabat sur 10 secondes si l'en-tête est absent
3. Relance la requête après l'attente

Format de sortie

JSON brut (sortie du connecteur)

Le connecteur renvoie du JSON brut depuis l'API HubSpot via handle_api_extraction(data, limit, return_type). Les données sont une liste de dictionnaires, exactement comme renvoyées par l'API.

Exemple d'objet CRM (contacts) :

{
  "id": "123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-03-20T14:22:00.000Z",
  "archived": false,
  "properties": {
    "email": "john@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "createdate": "2024-01-15T10:30:00.000Z"
  }
}

Sortie aplatie (lakehouse)

La platform aplatit automatiquement le JSON brut en une table plate. Les clés imbriquées deviennent des noms de colonnes avec des underscores :

Les noms de colonnes sont convertis : minuscules, points/caractères spéciaux remplacés par des underscores, doivent commencer par une lettre ou un underscore.

Limitations

• Les valeurs de propriétés sont toujours des chaînes, même les nombres et les dates. Convertissez-les dans votre traitement en aval.
• Les objets personnalisés ne sont pas pris en charge : le paramètre object_type est une liste de sélection fixe de 27 types CRM standards + owners. Les types d'objets personnalisés ne peuvent pas être extraits avec ce connecteur.
• Certains types d'objets nécessitent des plans payants : invoices, subscriptions et goals peuvent nécessiter Sales Hub ou Commerce Hub. Leads nécessite Sales Hub Professional+. Les objets Commerce (carts, discounts, fees, taxes) nécessitent Commerce Hub. L'API renvoie 403 si indisponible.
• Les soumissions de formulaires utilisent l'API v1 : le seul endpoint encore sur l'ancienne API v1. Utilise la pagination par décalage au lieu d'une pagination basée sur un curseur.
• Événements comportementaux : nécessitent Marketing Hub Enterprise et un ID d'enregistrement spécifique (impossible d'extraire tous les événements en masse).
• Les noms de colonnes dans le lakehouse sont convertis : properties.email devient properties_email. Ceci est géré par la platform, pas par le connecteur.

Aller plus loin

Si vous avez besoin d'une formation ou d'une assistance technique pour la mise en oeuvre de nos solutions, contactez votre commercial ou cliquez sur ce lien pour obtenir un devis et demander une analyse personnalisée de votre projet à nos experts de l’équipe Professional Services.

Posez vos questions, faites-nous part de vos commentaires et interagissez directement avec l’équipe qui développe la Data Platform sur le canal Discord dédié.

Si vous avez besoin d'une assistance concernant vos services OVHcloud, créez une demande depuis notre centre d'aide.

Rejoignez notre communauté d'utilisateurs.