> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mantrixflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot source

> Connect HubSpot as an Available Now source and deliver ten CRM streams to PostgreSQL or Airtable with dlt.

HubSpot is Available Now as a source-only connector. MantrixFlow uses
dlt to extract selected HubSpot data into isolated staging, applies your SQL/dbt
models, and delivers the result to existing PostgreSQL or Airtable tables.

<Note>
  Validated paths include **HubSpot → PostgreSQL** and **HubSpot → Airtable**.
  HubSpot cannot be selected as a destination.
</Note>

## Authentication

The connector supports a **HubSpot private app access token**. OAuth is not
currently supported.

1. In HubSpot, open **Settings → Integrations → Private Apps**.
2. Create or open a read-only private app.
3. Add only the read scopes required by the streams you plan to sync.
4. Copy the access token.
5. In MantrixFlow, open **Connections**, choose **Source**, and select
   **HubSpot**.
6. Enter a connection name and the private app access token.
7. Test the connection, then save it.

MantrixFlow encrypts the saved credential and masks it in connection responses.
Never place the token in SQL, pipeline names, logs, or AI chat.

## Supported streams

HubSpot exposes ten supported streams:

| Stream           | Required HubSpot scope        | Recommended mode | Primary key               |
| ---------------- | ----------------------------- | ---------------- | ------------------------- |
| Contacts         | `crm.objects.contacts.read`   | Incremental      | `id`                      |
| Companies        | `crm.objects.companies.read`  | Incremental      | `id`                      |
| Deals            | `crm.objects.deals.read`      | Incremental      | `id`                      |
| Tickets          | `tickets`                     | Incremental      | `id`                      |
| Owners           | `crm.objects.owners.read`     | Full Table       | `id`                      |
| Deal pipelines   | `crm.schemas.deals.read`      | Full Table       | `pipeline_id`, `stage_id` |
| Ticket pipelines | `tickets`                     | Full Table       | `pipeline_id`, `stage_id` |
| Products         | `crm.objects.products.read`   | Incremental      | `id`                      |
| Line items       | `crm.objects.line_items.read` | Incremental      | `id`                      |
| Quotes           | `crm.objects.quotes.read`     | Incremental      | `id`                      |

Discovery checks each stream against the connected account. A stream can appear
as available, missing a scope, unavailable for the account, or temporarily
unknown. This lets one valid token expose only the streams it can read without
returning CRM records during the connection test.

## Configure a HubSpot pipeline

1. Create or choose a PostgreSQL or Airtable destination connection.
2. Create a pipeline using the saved HubSpot source.
3. Open **Source** and click **Discover catalog**.
4. Select one or more available streams.
5. Configure the extraction window and custom-property option.
6. Preview the selected stream. HubSpot previews mask email local parts, phone
   numbers, and sensitive free-text fields.
7. Open **Destinations**, add the delivery target, and save it.
8. Open **Transformations**, select that destination, and create destination-owned
   SQL models for the selected streams. Save, validate, preview, and publish each
   revision.
9. Return to the destination editor and assign final tables and Upsert keys.
   Airtable also requires writable field mappings and merge fields.
10. Validate from **Overview**, click **Run all**, and inspect **Runs**.

The connector does not silently select every stream. At least one stream must be
selected before a run can start.

## UTC extraction window

Incremental object streams support:

* a required or previously saved UTC start time;
* an optional UTC end time, captured at run start when omitted; and
* a lookback from `0` through `604800` seconds, with a default of `3600`
  seconds.

The lookback overlaps adjacent runs so late updates can be read again and
deduplicated by the stable object key and update timestamp. Owners and the two
pipeline-definition streams are small full snapshots.

## Custom properties

Custom properties are supported for contacts, companies, deals, tickets,
products, line items, and quotes. Keep **Include custom properties** enabled to
request permitted custom fields, or disable it to use the stable default field
set. Sensitive HubSpot properties are excluded from discovery.

When an account has too many properties for a safe request, the connector can
fall back to the default property set for that stream and reports the fallback
in the run metadata. The raw `properties` value preserves the returned property
payload, while your SQL model promotes the fields you want into destination
columns.

## Destination requirements

Create or explicitly reconcile PostgreSQL destination schemas and tables before
delivery. For Airtable, create the table and fields first, then refresh and map
them in the destination editor. The pipeline runner does not create target tables
during a run.

* Use a primary key or stable merge key for each table.
* Keep model output columns aligned with destination column names and types.
* Use Upsert delivery for repeatable incremental runs.
* Keep `_mantrixflow_run_id` if you need row-level run lineage, and
  `extracted_at` if you need extraction-time auditing.
* Do not include internal `_dlt_*` staging columns in destination models.

Empty but valid HubSpot streams still produce a typed staging relation, so a
ten-stream run can validate and deliver successfully even when some streams
have no records.

## Current limitations

* OAuth, webhooks, write-back, custom objects, activities, associations, and
  property history are not supported.
* Quotes depend on the HubSpot products enabled for the connected account.
* Calculated-property-only changes may not advance the HubSpot update timestamp
  and may require a later full reconciliation.
* Line-item associations are not included.

For destination setup, see [PostgreSQL destination](/connections/destinations/postgresql)
or [Airtable destination](/connections/destinations/airtable).
For a complete ten-stream configuration with sample SQL and composite pipeline
keys, see the
[HubSpot-to-PostgreSQL example](/example/pipelines/hubspot-to-postgres).