--- title: "Extract HubSpot CRM and marketing data" description: "The HubSpot connector extracts data from your HubSpot account: contacts, companies, deals, tickets, pipelines, forms, marketing emails, and more" url: https://docs.ovhcloud.com/de/guides/public-cloud/data-platform/connectors-sources-hubspot lang: de lastUpdated: 2026-09-14 --- > For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/de/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/de/llms-full.txt. # Extract HubSpot CRM and marketing data ## 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](https://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 ``` ## 2. Recommended Scopes ### Minimum scopes (basic CRM) To extract contacts, companies, deals, and tickets: | Scope | Grants access to | | ---------------------------- | ----------------------------------------------- | | `crm.objects.contacts.read` | Contacts, calls, emails, meetings, notes, tasks | | `crm.objects.companies.read` | Companies | | `crm.objects.deals.read` | Deals + deal pipelines | | `tickets` | Tickets + ticket pipelines | | `crm.schemas.contacts.read` | Contact properties | | `crm.schemas.companies.read` | Company properties | | `crm.schemas.deals.read` | Deal properties | ### Additional scopes (as needed) | Scope | Grants access to | | --------------------------------------- | ------------------------ | | `forms` | Forms + form submissions | | `content` | Marketing emails | | `crm.lists.read` | Lists and segments | | `e-commerce` | Products | | `crm.objects.line_items.read` | Line items | | `crm.objects.quotes.read` | Quotes | | `crm.objects.feedback_submissions.read` | Feedback submissions | | `crm.objects.leads.read` | Leads (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) | Endpoint | Description | Parameters | | ---------------------------- | ------------------------------------------------------------------ | -------------------------------------------- | | **crm\_objects** | 27 CRM object types (contacts, companies, deals...) | object\_type, properties\_filter, max\_items | | **associations** | Relationships between objects (contact->deal, company->contact...) | from\_type, to\_type, max\_items | | **association\_definitions** | Available relationship types between objects | from\_type, to\_type | | **pipelines** | Pipelines with stages (deals or tickets) | pipeline\_object\_type | | **pipeline\_audit** | Audit log for a specific pipeline | pipeline\_object\_type, pipeline\_id | | **properties\_meta** | Property schema for an object type | property\_object\_type | | **property\_groups** | Property groups | property\_object\_type | | **lists** | Lists and segments | max\_items | | **list\_memberships** | Member record IDs for a specific list | list\_id, max\_items | ### Marketing | Endpoint | Description | Parameters | | --------------------- | ------------------------------- | -------------------- | | **marketing\_emails** | Email campaigns with statistics | max\_items | | **forms** | Form definitions | max\_items | | **form\_submissions** | Submissions for a specific form | form\_id, max\_items | | **campaigns** | Marketing campaigns | max\_items | ### CMS (content) | Endpoint | Description | Parameters | | ------------------ | ---------------------------- | ---------- | | **blog\_posts** | Blog articles | max\_items | | **site\_pages** | Website pages | max\_items | | **landing\_pages** | Landing pages | max\_items | | **hubdb\_tables** | HubDB structured data tables | max\_items | ### Automation | Endpoint | Description | Parameters | | ------------- | -------------------- | ---------- | | **workflows** | Automation workflows | max\_items | | **sequences** | Sales sequences | max\_items | ### Settings / Admin | Endpoint | Description | Parameters | | -------------------- | ------------------------ | -------------------------------------------------- | | **users** | Account users | max\_items | | **imports** | CRM import history | max\_items | | **crm\_schemas** | Custom object schemas | max\_items | | **custom\_events** | Behavioral events | event\_object\_type, event\_object\_id, max\_items | | **timeline\_events** | Timeline event templates | app\_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](#1-get-an-api-token) 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](https://docs.ovhcloud.com/de/guides/public-cloud/data-platform/landing-page-developers-python-sdk.md). ::: ## 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: | Plan | Accessible endpoints | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Free** | crm\_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](https://docs.ovhcloud.com/de/guides/public-cloud/data-platform/connectors-sources-hubspot-technical-reference.md). ::: ## Go further If you need training or technical assistance to implement our solutions, contact your sales representative or click on [this link](https://www.ovhcloud.com/de/professional-services/) 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](https://discord.gg/ovhcloud). If you need support with your OVHcloud services, create a request in our [Help Centre](https://help.ovhcloud.com/csm?id=csm_get_help). Join our [community of users](https://community.ovhcloud.com/).