canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-custom-objects

# HubSpot CRM Custom Objects

Jentic publishes the only available OpenAPI specification for HubSpot CRM Custom Objects, keeping it validated and agent-ready. Define and operate on bespoke CRM object types that extend HubSpot beyond standard contacts, companies, deals, and tickets. Store industry-specific records - such as vehicles, properties, or subscriptions - with full association, search, batch, and merge support across the HubSpot CRM graph. Requires an Enterprise-tier HubSpot account.

## For AI agents

Create, query, batch-process, and associate custom CRM object records in HubSpot. Supports search, merge, upsert, and cross-object associations for any user-defined object type.

## Scope

Does not handle custom object schema definitions, contact management, deal pipelines, or marketing automation - use for custom object record operations only.

## Capabilities

- Search custom object records using filters, property values, and full-text queries
- Batch-create or upsert hundreds of custom object records in a single API call
- Associate custom objects with contacts, companies, deals, or other custom types
- Merge duplicate custom object records into a single canonical entry
- Retrieve individual records with selected properties and association expansions
- Bulk-read custom objects by record IDs or a unique property identifier
- Remove associations between custom objects and standard CRM records

## Use cases

### AI Agent Custom Object Automation

AI agents use HubSpot CRM Custom Objects through Jentic to automate record creation and association for industry-specific data models. An agent can search for matching records by property value, batch-upsert new entries from external systems, and wire associations to standard HubSpot objects - all without manual CRM configuration. Through Jentic, agents discover the correct endpoints via intent search, load the schema, and execute operations in under a minute.

Example prompt: Search for custom object records of type 'vehicle' where the 'vin' property matches a given value, then associate the matching record with an existing contact by contact ID

### Industry-Specific CRM Data Modeling

Extend HubSpot CRM to store domain-specific records that do not fit contacts, companies, deals, or tickets. Custom objects let real estate firms track properties, auto dealers track vehicles, or SaaS companies track subscription tiers - each with typed properties, associations, and searchability identical to native HubSpot objects. The API supports up to 10 custom object definitions on Enterprise plans.

Example prompt: Create a batch of 50 custom object records of type 'property_listing' with address, price, and status properties using the batch/create endpoint

### Duplicate Record Merging

Identify and merge duplicate custom object records to maintain data hygiene across the CRM. The merge endpoint combines two records by retaining the primary record's ID and associations while absorbing the secondary record's unique data. This is critical for pipelines that ingest data from multiple sources where duplicates are common.

Example prompt: Merge custom object record ID 456 into primary record ID 123 of type 'subscription' using the merge endpoint

### Cross-Object Association Management

Build a connected CRM graph by associating custom objects with contacts, companies, deals, tickets, or other custom types. The API supports both labeled and default association types, enabling relationship semantics like 'owned by' or 'related to'. Associations are bidirectional and immediately reflected in the HubSpot UI timeline.

Example prompt: Create a default association between a custom object record of type 'vehicle' (ID 789) and a contact (ID 101) using the PUT associations endpoint

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /crm/v3/objects/{objectType}/search | Search custom objects by property filters |
| POST | /crm/v3/objects/{objectType} | Create a single custom object record |
| POST | /crm/v3/objects/{objectType}/batch/create | Batch-create custom object records |
| POST | /crm/v3/objects/{objectType}/batch/upsert | Batch-upsert records by unique property |
| POST | /crm/v3/objects/{objectType}/merge | Merge two custom object records |
| PUT | /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId} | Associate a custom object with another record |
| GET | /crm/v3/objects/{objectType}/{objectId} | Retrieve a single custom object record |
| GET | /crm/v3/objects/{objectType} | List custom object records by type |

## Key resources

- **Custom Objects** — Create, read, update, delete, search, merge, and batch-process records of any custom object type
- **Associations** — Link custom object records to contacts, companies, deals, tickets, or other custom objects
- **Batch Operations** — Bulk create, read, update, upsert, and archive custom object records
- **Search** — Filter and query custom object records by property values and full-text search

## Why Jentic

- **Setup:** Wiring the HubSpot Custom Objects API by hand means handling its OAuth 2.0 authorization-code flow, targeting api.hubapi.com, and passing the objectType path parameter plus association, batch, and search payloads yourself. Through Jentic you install once, import HubSpot Custom Objects from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The object type travels in the URL path (/crm/v3/objects/{objectType}/...) and HubSpot gates access with per-object custom OAuth scopes, so you grant only the custom object scopes your agent needs and you choose which operations it may call: you can allow creating and searching records while leaving destructive operations like merge out of the allowed set unless you add them.
- **Credential handling:** Your HubSpot OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a custom object record in HubSpot' or 'search custom objects by property', and Jentic returns the matching Custom Objects operation with its input schema, including the objectType path parameter, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Salesforce Shopper Products** — Salesforce Commerce Cloud product catalog API for e-commerce scenarios, broader platform but different CRM model
- **Pipedrive API** — Sales-focused CRM with simpler custom fields but no full custom object types
- **Zoho CRM API** — Full CRM with custom modules similar to HubSpot custom objects
- **HubSpot CRM Contacts** — Standard contacts API that custom objects frequently associate with

## FAQ

### Why is there no official OpenAPI spec for HubSpot CRM Custom Objects?

HubSpot does not publish an OpenAPI specification for their Custom Objects API. Jentic generates and maintains this spec so that AI agents and developers can call HubSpot CRM Custom Objects via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the HubSpot CRM Custom Objects API use?

The API uses OAuth 2.0 with scopes specific to CRM object access. Tokens must include the crm.objects.custom.read and crm.objects.custom.write scopes. Through Jentic, OAuth tokens are stored encrypted in your Jentic One instance and agents receive scoped access without handling refresh flows directly.

### Can I batch-upsert custom object records with this API?

Yes. The POST /crm/v3/objects/{objectType}/batch/upsert endpoint accepts up to 100 records per call. Each record is matched by a unique property you specify (such as an external ID), and existing matches are updated while new records are created. This avoids duplicates when syncing from external systems.

### How do I search for custom object records through Jentic?

Use Jentic's intent search with a query like 'search custom objects in HubSpot'. Jentic returns the POST /crm/v3/objects/{objectType}/search operation with its input schema. The search endpoint accepts filter groups with property name, operator, and value to return matching records. Install the SDK with pip install jentic to get started.

### What are the rate limits for the HubSpot CRM Custom Objects API?

HubSpot applies a burst limit of 100 requests per 10 seconds per OAuth app and a daily limit of 250,000 API calls for Enterprise accounts. Batch endpoints count as a single request regardless of the number of records included, making them more rate-efficient for bulk operations.

### Can I associate custom objects with standard HubSpot CRM objects?

Yes. The PUT /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId} endpoint creates associations between any custom object record and contacts, companies, deals, tickets, or other custom objects. Associations are bidirectional and support both default and labeled relationship types.

### Do I need a HubSpot Enterprise account to use Custom Objects?

Yes. Custom objects are only available on HubSpot Enterprise plans. Free, Starter, and Professional tiers cannot define or use custom object types. The API requires Enterprise-level OAuth credentials with custom object scopes enabled.

### Can I limit what my agent is allowed to do with the HubSpot CRM Custom Objects API?

Yes. Because Jentic One is self-hosted, you set the rules that decide which Custom Objects operations your agent can call and which credentials it uses, and HubSpot's per-object custom OAuth scopes mean you grant only the object scopes the agent actually needs. For example, you can allow the agent to search and create records via the search and batch/create endpoints while leaving destructive operations like the merge endpoint out of the allowed set. The OAuth token stays with your own instance and is injected only at execution time, so the agent never sees it directly.