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:
- Service key (recommended). HubSpot recommends service keys for new integrations within your own account.
- Project app with static auth, distributed privately, if you already build apps on HubSpot's developer platform.
- 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
.read scopes.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.
| Scope | Unlocks | Required |
|---|---|---|
crm.objects.contacts.read | Contacts | For contacts |
crm.objects.companies.read | Companies | For companies |
crm.objects.deals.read | Deals and deal pipelines | For deals |
crm.objects.tickets.read | Tickets and ticket pipelines | For tickets |
crm.objects.line_items.read | Line items | For line items |
crm.objects.products.read | Products | For products |
crm.objects.quotes.read | Quotes | For quotes |
crm.objects.custom.read | Custom objects (Enterprise only) | Optional |
crm.schemas.custom.read | Custom object definitions (Enterprise only) | Optional |
crm.objects.owners.read | Owners (owner names) | For owners |
Set up the connection
auth (the account details) and permissions (one record of each object).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 property | Dataset type |
|---|---|
string, phone number | string |
number | number, read exactly. A value that a number cannot hold exactly fails with TYPE_MISMATCH: bind the field as a decimal |
date | date |
datetime | datetime (UTC) |
bool | boolean |
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 withcontainsPii: true, otherwise the selection is refused.
Limits
| Limit | Value |
|---|---|
| Rows per read | 50,000 |
| Fields per read | 100 |
| Pages per read | Free 100, Pro 600 (100 records per page) |
| Associated object types | 3 |
| Read deadline | 30 s interactive, 300 s scheduled |
| Objects listed | 500 |
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
| Code | Cause | What to do |
|---|---|---|
PROVIDER_ACCESS_DENIED, stage auth | The key was rejected | Create a new key and replace the configuration |
PROVIDER_ACCESS_DENIED, stage permissions | A scope is missing. details.missingScopes names it | Add the scope to the key, then test again |
RATE_LIMITED | The burst or daily limit is used up | Retry after details.retryAt |
TYPE_MISMATCH | A number value does not fit a number exactly | Bind the field as a decimal |
LIMIT_EXCEEDED | More than the plan's pages or 50,000 rows | Select a smaller object, or upgrade to Pro |
INCOMPLETE_DATA | Paging could not be proven complete, or an association list has more pages | Retry, or use the first associated id |
SCHEMA_CHANGED | HubSpot returned no properties for the object | Check the object in HubSpot |
PERMISSION_DENIED | The object is not selected on the connection | Select it, or replace the configuration |
VALIDATION_FAILED | An unknown field, or personal data selected without containsPii | Fix the selection |