Docs
Connections

HubSpot

Connect HubSpot CRM with a service key, grant read scopes, and read contacts, companies, deals, tickets, custom objects, owners and pipelines.

A HubSpot connection reads CRM records with a read-scoped key. Xentropy reads through HubSpot's list endpoints, so a full read is not cut at the 10,000-result cap of HubSpot search.

Availability

HubSpot is not yet generally available on xentropy.ai. Contact support@xentropy.ai to request access. Until it is enabled for your account, it does not appear in the catalogue and its reads fail with PROVIDER_DISABLED.

Choose a credential

Xentropy accepts any HubSpot Bearer credential that has the read scopes below:

  1. Service key (recommended). HubSpot recommends service keys for new integrations within your own account.
  2. Project app with static auth, distributed privately, if you already build apps on HubSpot's developer platform.
  3. Legacy private app token. HubSpot no longer lets you create new legacy private apps, but the token of an existing one keeps working.

Create a service key

In HubSpot, open Settings → Development → Keys → Service keys and create a key.
Add the read scopes from the table below for the objects you want to read. Add only .read scopes.
Create the key and copy it.

Required scopes

The form lists these scopes with a copy button. Test connection reads one record of each selected object and names any missing scope.

ScopeUnlocksRequired
crm.objects.contacts.readContactsFor contacts
crm.objects.companies.readCompaniesFor companies
crm.objects.deals.readDeals and deal pipelinesFor deals
crm.objects.tickets.readTickets and ticket pipelinesFor tickets
crm.objects.line_items.readLine itemsFor line items
crm.objects.products.readProductsFor products
crm.objects.quotes.readQuotesFor quotes
crm.objects.custom.readCustom objects (Enterprise only)Optional
crm.schemas.custom.readCustom object definitions (Enterprise only)Optional
crm.objects.owners.readOwners (owner names)For owners

Set up the connection

Open Connections, choose New connection, then HubSpot.
Name the connection and paste the service key or access token.
Choose Test connection. The stages are auth (the account details) and permissions (one record of each object).
Choose Save connection. Then open the connection's resources, pick an object and its fields, preview 100 rows and save a dataset.

HubSpot needs no IP allowlist: Xentropy connects only to api.hubapi.com.

Resources

  • Standard objects: contacts, companies, deals, tickets, line items, products and quotes.
  • Custom objects (Enterprise accounts), listed by their object type id (for example 2-1234567).
  • Owners, one row per owner.
  • Pipeline stages of deals and tickets, one row per stage.

Archived records are left out unless the dataset asks for them.

Fields

Field types come from HubSpot's property definitions and do not change between reads:

HubSpot propertyDataset type
string, phone numberstring
numbernumber, read exactly. A value that a number cannot hold exactly fails with TYPE_MISMATCH: bind the field as a decimal
datedate
datetimedatetime (UTC)
boolboolean
enumeration (single choice)string, with an optional label field
enumeration (checkboxes)JSON list, or HubSpot's ; text

Deal and ticket stages and pipelines can add a label field. Owner properties can add an owner-name field. Associations (up to 3 object types) give the first associated id, or a JSON list of ids.

Decimal fields

If a number property holds values beyond what a number can store exactly (very large ids or amounts), the read fails with TYPE_MISMATCH and names the field and row. Choose Bind as decimal for that field in the field picker, or set decimalFields in the dataset's HubSpot resource. The field is then read as an exact decimal.

Personal data

Contact name, email, phone, address, birth date and IP location properties, any email or phone property on other objects, and owner emails are personal data. They are marked Personal data in the field picker and are off by default.

  • If you select one, the dataset is marked as containing personal data (containsPii). The API and agents must confirm this with containsPii: true, otherwise the selection is refused.

Limits

LimitValue
Rows per read50,000
Fields per read100
Pages per readFree 100, Pro 600 (100 records per page)
Associated object types3
Read deadline30 s interactive, 300 s scheduled
Objects listed500

HubSpot pages hold 100 records, so on the Free plan a read stops at about 10,000 records with LIMIT_EXCEEDED. The Pro plan reads up to the 50,000-row frame limit.

Xentropy follows HubSpot's burst and daily limits. When the daily limit is used up, the read fails with RATE_LIMITED and details.retryAt is the next midnight in your HubSpot account's time zone.

Errors

CodeCauseWhat to do
PROVIDER_ACCESS_DENIED, stage authThe key was rejectedCreate a new key and replace the configuration
PROVIDER_ACCESS_DENIED, stage permissionsA scope is missing. details.missingScopes names itAdd the scope to the key, then test again
RATE_LIMITEDThe burst or daily limit is used upRetry after details.retryAt
TYPE_MISMATCHA number value does not fit a number exactlyBind the field as a decimal
LIMIT_EXCEEDEDMore than the plan's pages or 50,000 rowsSelect a smaller object, or upgrade to Pro
INCOMPLETE_DATAPaging could not be proven complete, or an association list has more pagesRetry, or use the first associated id
SCHEMA_CHANGEDHubSpot returned no properties for the objectCheck the object in HubSpot
PERMISSION_DENIEDThe object is not selected on the connectionSelect it, or replace the configuration
VALIDATION_FAILEDAn unknown field, or personal data selected without containsPiiFix the selection

On this page