For AI agents: the complete documentation index is available at https://docs.dataplatform.ovh.net/llms.txt, the full documentation bundle is available at https://docs.dataplatform.ovh.net/llms-full.txt, and this page is available as Markdown at https://docs.dataplatform.ovh.net/connectors-sources-hubspot.md.
  • 🇬🇧 English

    • Extract HubSpot CRM and marketing data

    The HubSpot connector extracts data from your HubSpot account: contacts, companies, deals, tickets, pipelines, forms, marketing emails, and more

    Objective

    The HubSpot connector extracts data from your HubSpot account: contacts, companies, deals, tickets, pipelines, forms, marketing emails, and more.

    25 endpoint types covering the full HubSpot API: CRM, Marketing, CMS, Automation, and Settings.

    The connector returns raw JSON from the HubSpot API. The platform automatically flattens nested objects into columns and stores the result in the lakehouse. No manual schema definition needed.

    Info

    Prerequisites: A HubSpot account (the free plan is sufficient for API access. No paid plan required) with at least a few test records (contacts, companies) so you have data to extract. Sign up at app.hubspot.com/signup-hubspot/crm.

    1. Get an API Token

    Create a Private App

    1. Log in to HubSpot
    2. Go to Settings (gear icon) > Integrations > Private Apps
    3. Click Create a private app
    4. Give it a name (e.g. data-connector)
    5. Go to the Scopes tab and select the required permissions (see next section)
    6. Click Create app > Continue creating
    7. Copy the generated token (starts with pat-na1-... or pat-eu1-...)
    Info

    Note: Private Apps may appear under a "Legacy" section in HubSpot's UI, but they remain the standard for server-side API integrations. "Personal Access Keys" only work for the HubSpot CLI, NOT for the REST API.

    Configure Credentials

    Paste your token in the HubSpot API Key field:

    pat-eu1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    Minimum scopes (basic CRM)

    To extract contacts, companies, deals, and tickets:

    ScopeGrants access to
    crm.objects.contacts.readContacts, calls, emails, meetings, notes, tasks
    crm.objects.companies.readCompanies
    crm.objects.deals.readDeals + deal pipelines
    ticketsTickets + ticket pipelines
    crm.schemas.contacts.readContact properties
    crm.schemas.companies.readCompany properties
    crm.schemas.deals.readDeal properties

    Additional scopes (as needed)

    ScopeGrants access to
    formsForms + form submissions
    contentMarketing emails
    crm.lists.readLists and segments
    e-commerceProducts
    crm.objects.line_items.readLine items
    crm.objects.quotes.readQuotes
    crm.objects.feedback_submissions.readFeedback submissions
    crm.objects.leads.readLeads (Sales Hub Pro+)
    Tip

    Start with minimum scopes. You can always add more later in your Private App settings.

    3. Available Endpoint Types

    CRM (relational data)

    EndpointDescriptionParameters
    crm_objects27 CRM object types (contacts, companies, deals...)object_type, properties_filter, max_items
    associationsRelationships between objects (contact->deal, company->contact...)from_type, to_type, max_items
    association_definitionsAvailable relationship types between objectsfrom_type, to_type
    pipelinesPipelines with stages (deals or tickets)pipeline_object_type
    pipeline_auditAudit log for a specific pipelinepipeline_object_type, pipeline_id
    properties_metaProperty schema for an object typeproperty_object_type
    property_groupsProperty groupsproperty_object_type
    listsLists and segmentsmax_items
    list_membershipsMember record IDs for a specific listlist_id, max_items

    Marketing

    EndpointDescriptionParameters
    marketing_emailsEmail campaigns with statisticsmax_items
    formsForm definitionsmax_items
    form_submissionsSubmissions for a specific formform_id, max_items
    campaignsMarketing campaignsmax_items

    CMS (content)

    EndpointDescriptionParameters
    blog_postsBlog articlesmax_items
    site_pagesWebsite pagesmax_items
    landing_pagesLanding pagesmax_items
    hubdb_tablesHubDB structured data tablesmax_items

    Automation

    EndpointDescriptionParameters
    workflowsAutomation workflowsmax_items
    sequencesSales sequencesmax_items

    Settings / Admin

    EndpointDescriptionParameters
    usersAccount usersmax_items
    importsCRM import historymax_items
    crm_schemasCustom object schemasmax_items
    custom_eventsBehavioral eventsevent_object_type, event_object_id, max_items
    timeline_eventsTimeline event templatesapp_id

    4. Add a HubSpot source on Data Platform

    1. In the Data Platform Connectors, find HubSpot in the source store and click Select.
    2. Paste the Private App token from step 1 into the HubSpot API Key field.
    3. Click Connect to verify the credentials.
    4. Click Add an Endpoint, choose an endpoint type from the dropdown (e.g. crm_objects), then fill in the parameters that endpoint requires (for example object_type: contacts, an optional properties_filter, and an optional max_items).
    5. Repeat step 4 for every additional endpoint you want to ingest in this source. Each endpoint becomes a separate table in the lakehouse.
    6. Name the source and click Create.
    Warning

    The technical name cannot be changed after the source is created. It is used when opening the source via the Data Platform SDK.

    5. Quick Example: Extract Contacts

    1. Endpoint: crm_objects
    2. Object Type: contacts
    3. Properties Filter: email, firstname, lastname, phone, company, jobtitle
    4. Max Items: 100 (or empty to extract all)

    The connector returns raw JSON from the HubSpot API. The platform automatically flattens nested objects (e.g. properties.email becomes a column properties_email) and stores the result in the lakehouse.

    6. Best Practices

    Use the properties filter

    By default, the connector uses HubSpot's native default set (6 core fields for contacts: email, firstname, lastname, createdate, lastmodifieddate, hs_object_id). Use properties_filter to pick a specific list of properties.

    Start with max_items

    When setting up, set max_items to 10 or 100 to test quickly. Remove the limit once you're satisfied with the output.

    Pipelines as a reference table

    Extract pipelines separately to get a reference table. You can then join with deals/tickets on the pipeline and stage fields.

    Use properties_meta to discover fields

    The properties_meta endpoint returns the full data dictionary for any object type. Useful to find out which fields exist and their types.

    7. HubSpot Plan Limits

    Some endpoints require paid plans:

    PlanAccessible endpoints
    Freecrm_objects, pipelines, properties_meta, forms, blog_posts, site_pages, landing_pages, associations, property_groups, lists, marketing_emails, form_submissions, pipeline_audit, list_memberships
    Pro+ workflows, sequences, users, campaigns
    Enterprise+ conversations, custom_events, timeline_events, crm_schemas, hubdb_tables, imports

    Endpoints not available on your plan or missing the required scope return a 403 error. The connector does not catch these errors. The extraction will fail with an HTTPError. Make sure your Private App has the necessary scopes enabled before selecting an endpoint.

    Info

    Note: The plan classification above is approximate. Some 403 errors may be caused by missing scopes on your Private App rather than plan limitations. If an endpoint returns 403, check your Private App's scope configuration first.

    Info

    For detailed technical information (auth internals, full endpoint reference, scopes, pagination, output format, limitations), see the HubSpot Technical Reference.

    Go further

    If you need training or technical assistance to implement our solutions, contact your sales representative or click on this link to get a quote and ask our Professional Services experts for a custom analysis of your project.

    Ask questions, give your feedback and interact directly with the team building the Data Platform on the dedicated Discord channel.

    If you need support with your OVHcloud services, create a request in our Help Centre.

    Join our community of users.