HubSpot: Technical Reference

Objective

This is the technical companion to the main HubSpot connector documentation. It covers authentication internals, the full endpoint reference, scopes, pagination, output format, and limitations, everything needed to integrate the connector into a data pipeline.

Authentication

Supported Methods

All methods use the same Bearer header:

Authorization: Bearer {token}

Deprecated authentication methods

Credentials Format

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

Architecture

The connector returns raw JSON from the HubSpot API. The platform takes over from there. It auto-discovers the schema from the JSON payload, flattens nested objects into dot-notation columns (slugified to lowercase with underscores), and stores the result in the lakehouse, queryable via Trino. Any new field HubSpot adds to an object appears automatically on the next extraction; you don't define a schema, list columns, or write any transformation code.

The connector itself is responsible for authentication (Bearer token), endpoint routing, pagination (cursor or offset depending on the endpoint), and rate-limit retries.

CRM Object Types

27 Standard Objects

The connector exposes the 27 standard HubSpot CRM object types. Each is reachable via /crm/v3/objects/{object_type} (except owners, see below).

Core CRM

Engagements

E-commerce & Sales

Commerce

Commerce Hub

Sales Hub

Service & Scheduling

Special: Owners

Owners use a dedicated endpoint (GET /crm/v3/owners) instead of /crm/v3/objects/owners. The connector handles this automatically when object_type=owners is selected.

Endpoint Reference

crm_objects

Extract records from any CRM object type.

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

Pagination: Cursor-based (paging.next.after)

Output: Raw JSON. Each record has id, createdAt, updatedAt, archived, and a nested properties dict containing all requested property values.

Properties behavior:

• Empty filter: fetches ALL properties via GET /crm/v3/properties/{type} first, then requests all of them
• With filter: requests only the specified properties
• HubSpot returns all property values as strings (even numbers and dates)

associations

Extract relationships between CRM objects.

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

Pagination: Cursor-based on source objects, batch POST for association lookup (max 1000 IDs per request)

Output: Raw JSON. Each result contains from and to objects with IDs and association metadata.

association_definitions

Get the available association types between two object types.

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

Pagination: None (single GET)

Output: Raw JSON, association type definitions with category, type ID, and label.

pipelines

Extract pipeline definitions with their stages.

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

Pagination: None (single GET, returns all pipelines)

Output: Raw JSON. Each pipeline contains id, label, displayOrder, createdAt, updatedAt, and a nested stages array. The platform flattens stages into separate rows automatically.

pipeline_audit

Audit log for a specific pipeline.

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

Pagination: None (single GET)

Output: Raw JSON, audit entries as returned by the API.

properties_meta

Extract the data dictionary (property schema) for an object type.

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

Pagination: None (single GET)

Output: Raw JSON. Each property has name, label, type, fieldType, groupName, description, and more.

property_groups

Extract property groups for an object type.

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

Pagination: None (single GET)

Output: Raw JSON, group definitions as returned by the API.

lists

Extract list and segment definitions.

API: GET /crm/v3/lists

Pagination: Cursor-based

Output: Raw JSON, list definitions as returned by the API.

list_memberships

Get member record IDs from a specific list.

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

Pagination: Cursor-based

Output: Raw JSON, membership records as returned by the API.

marketing_emails

Extract marketing email definitions with statistics.

API: GET /marketing/v3/emails

Pagination: Cursor-based

Output: Raw JSON, email campaign data with nested statistics, flattened by the platform.

forms

Extract form definitions.

API: GET /marketing/v3/forms

Pagination: Cursor-based

Output: Raw JSON, form definitions as returned by the API.

form_submissions

Extract submissions for a specific form.

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

Pagination: Offset-based (v1 API, uses offset + hasMore, NOT cursor-based)

Output: Raw JSON, submission data as returned by the API.

conversations

Extract conversation threads (chat, email, bot).

API: GET /conversations/v3/conversations/threads

Pagination: Cursor-based

Output: Raw JSON, thread data as returned by the API.

Requires: Conversations scope + appropriate HubSpot plan

campaigns

Extract marketing campaign definitions.

API: GET /marketing/v3/campaigns

Pagination: Cursor-based

Output: Raw JSON, campaign data as returned by the API.

blog_posts

Extract CMS blog articles.

API: GET /cms/v3/blogs/posts

Pagination: Cursor-based

Output: Raw JSON, blog post data (title, content, author, publish date, etc.).

site_pages

Extract CMS website pages.

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

Pagination: Cursor-based

Output: Raw JSON, page data as returned by the API.

landing_pages

Extract CMS landing pages.

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

Pagination: Cursor-based

Output: Raw JSON, page data as returned by the API.

workflows

Extract automation workflow definitions.

API: GET /automation/v3/workflows

Pagination: None (single GET, data key is workflows, not results)

Output: Raw JSON, workflow definitions as returned by the API.

sequences

Extract sales sequence definitions.

API: GET /automation/v4/sequences

Pagination: Cursor-based

Output: Raw JSON, sequence data as returned by the API.

Requires: Sales Hub Pro+

users

Extract account users.

API: GET /settings/v3/users

Pagination: Cursor-based

Output: Raw JSON, user data as returned by the API.

imports

Extract CRM import history.

API: GET /crm/v3/imports

Pagination: Cursor-based

Output: Raw JSON, import records as returned by the API.

crm_schemas

Extract custom object schema definitions.

API: GET /crm/v3/schemas

Pagination: None (single GET)

Output: Raw JSON, schema definitions as returned by the API.

custom_events

Extract behavioral events for a specific CRM record.

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

Pagination: Cursor-based (with extra_params)

Output: Raw JSON, event data as returned by the API.

Requires: Marketing Hub Enterprise

timeline_events

Extract timeline event templates for an integration app.

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

Pagination: None (single GET)

Output: Raw JSON, event template data as returned by the API.

hubdb_tables

Extract HubDB table definitions.

API: GET /cms/v3/hubdb/tables

Pagination: Cursor-based

Output: Raw JSON, table definitions as returned by the API.

Scopes by Endpoint

CRM Objects

Other Endpoints

For endpoints not listed above (workflows, sequences, users, imports, crm_schemas, conversations, custom_events, hubdb_tables, timeline_events), refer to HubSpot's scope reference for the authoritative scope name.

Pagination

The connector uses three pagination strategies depending on the endpoint:

Cursor-based (most endpoints)

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

Response:

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

When paging.next.after is absent, all data has been fetched.

Offset-based (form submissions only)

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

Response:

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

When hasMore is false, all data has been fetched.

No pagination (single GET)

Some endpoints return all data in a single response: pipelines, pipeline_audit, properties_meta, property_groups, association_definitions, workflows, timeline_events, crm_schemas.

Rate Limits

Limits by Plan

Refer to HubSpot's official rate limit documentation for current limits. Limits vary by plan and API endpoint.

Rate Limit Handling

The connector automatically handles 429 Too Many Requests responses:

1. Reads the Retry-After header (seconds to wait)
2. Falls back to 10 seconds if header is missing
3. Retries the request after waiting

Output Format

Raw JSON (connector output)

The connector returns raw JSON from the HubSpot API via handle_api_extraction(data, limit, return_type). The data is a list of dicts, exactly as returned by the API.

Example CRM object (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"
  }
}

Flattened output (lakehouse)

The platform automatically flattens the raw JSON into a flat table. Nested keys become column names with underscores:

Column names are slugified: lowercase, dots/special chars replaced by underscores, must start with a letter or underscore.

Limitations

• Property values are always strings, even numbers and dates. Cast them in your downstream processing.
• Custom objects are not supported: the object_type parameter is a fixed select list of 27 standard CRM types + owners. Custom object types cannot be extracted with this connector.
• Some object types require paid plans: invoices, subscriptions, and goals may require Sales Hub or Commerce Hub. Leads require Sales Hub Professional+. Commerce objects (carts, discounts, fees, taxes) require Commerce Hub. The API returns 403 if unavailable.
• Form submissions use v1 API: the only endpoint still on the legacy v1 API. Uses offset pagination instead of cursor-based.
• Behavioral events: require Marketing Hub Enterprise and a specific record ID (cannot bulk-extract all events).
• Column names in lakehouse are slugified: properties.email becomes properties_email. This is handled by the platform, not the connector.

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.