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

# HubSpot CRM Custom Objects

The HubSpot CRM Custom Objects API manages records for object types beyond the four standard CRM objects (contacts, companies, deals, tickets) on the HubSpot EU region. It supports single-record create, read, update and archive plus high-volume batch and search operations, so agents and integrations can store domain-specific entities such as subscriptions, properties, or vehicles directly in the CRM. Custom object record management requires HubSpot Enterprise; schema definitions are managed via the separate CRM Schemas API.

## For AI agents

Create, read, update, archive and search records of HubSpot custom object types via batch and single-record endpoints on the EU region.

## Scope

Does not define custom object schemas, manage standard objects (contacts, companies, deals, tickets), or handle marketing automation - use for managing records of pre-defined custom object types only.

## Capabilities

- Create a single custom object record of a given objectType with property values
- Read a custom object record by internal ID with selectable properties and associations
- Update a custom object record by ID with partial property changes
- Search custom object records by property filters with sort and pagination
- Batch create, read, update, upsert or archive up to 100 records in one call
- Merge two custom object records of the same type into one canonical record
- Associate a custom object record with another CRM record using the default association

## Use cases

### Subscription record management

Store SaaS subscriptions as a custom object in HubSpot so renewal dates and MRR live alongside the company record. POST `/crm/v3/objects/{objectType}` creates a subscription with properties like start_date and plan_tier; GET `/crm/v3/objects/{objectType}/{objectId}` reads it back for renewal workflows. Custom objects require Enterprise tier.

Example prompt: POST `/crm/v3/objects/subscription` with properties for plan_tier, start_date and mrr, then verify the returned id.

### Bulk inventory sync

Sync thousands of property listings from an external system into HubSpot as a Property custom object so sales reps can build deals against them. POST `/crm/v3/objects/{objectType}/batch/upsert` handles up to 100 records per call with idempotent upsert by a unique property, replacing manual CSV imports.

Example prompt: POST `/crm/v3/objects/property/batch/upsert` with up to 100 records keyed by external_id, then check for any errors in the response array.

### Targeted record search

Find every custom object record matching multi-property filters, sorted and paginated, without scanning the full collection. POST `/crm/v3/objects/{objectType}/search` accepts filterGroups, sorts and a limit, returning matching record IDs and properties. This is the fastest way to power an internal lookup tool.

Example prompt: POST `/crm/v3/objects/vehicle/search` with a filterGroup of {propertyName: vin, operator: EQ, value: '1HG...'} and inspect the matching record.

### Cross-object association

Tie a custom object record to a standard object so HubSpot timelines and reports surface the relationship. PUT `/crm/v3/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}` creates a default association in one call without needing to know the labelled type ID.

Example prompt: PUT `/crm/v3/objects/property/{propertyId}/associations/default/deals/{dealId}` to associate a property listing with a deal.

### Agent-driven CRM record management via Jentic

An AI agent receives a webhook from a billing system, looks up the matching subscription custom object via search, updates the renewal_date property, and confirms the change. Jentic mediates the OAuth scopes so the agent only ever sees the scoped token for the active call.

Example prompt: Search Jentic for 'update a HubSpot custom object record', load PATCH `/crm/v3/objects/{objectType}/{objectId}`, and execute with the new renewal_date.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/crm/v3/objects/{objectType}` | List custom object records |
| POST | `/crm/v3/objects/{objectType}` | Create a custom object record |
| GET | `/crm/v3/objects/{objectType}/{objectId}` | Read a record by ID |
| PATCH | `/crm/v3/objects/{objectType}/{objectId}` | Update a record by ID |
| POST | `/crm/v3/objects/{objectType}/batch/create` | Create a batch of records |
| POST | `/crm/v3/objects/{objectType}/batch/upsert` | Upsert a batch by unique property |
| POST | `/crm/v3/objects/{objectType}/search` | Search records by property filters |
| POST | `/crm/v3/objects/{objectType}/merge` | Merge two records of the same type |

## Key resources

- **Basic** — Single-record CRUD operations on custom object records by ID
- **Batch** — High-volume create, read, update, upsert and archive operations
- **Search** — Property-based search with filters, sorts and pagination
- **Advanced** — Merge operations and default associations between records

## Why Jentic

- **Setup:** Wiring HubSpot CRM Custom Objects by hand means running its OAuth2 flow, refreshing tokens against the api.hubapi.com host, and mapping the property-bag CRUD, batch, search, and merge operations yourself. Through Jentic you install once, import HubSpot CRM Custom Objects from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** HubSpot puts the object type and record id in the URL path (`/crm/v3/objects/{objectType}/{objectId}`), so a rule can pin your agent to reading and updating records of one object type and nothing else. You choose the operations it may call, so a merge or batch write is not included unless you add it.
- **Credential handling:** Your HubSpot OAuth 2.0 refresh token and client secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot custom object record' or 'search custom object records', and Jentic returns the matching operation with its property-bag input schema so the agent calls the right endpoint without mapping the batch, search, and association variants.

## Related APIs

- **HubSpot CRM Schemas** — Defines the custom object types whose records this API manages
- **Salesforce API** — Salesforce custom objects offer the same modelling pattern in a different CRM
- **Pipedrive API** — Pipedrive's custom objects (Products, Activities) cover lighter custom modelling needs
- **Zoho CRM API** — Zoho CRM offers custom modules with similar create/search/associate semantics

## FAQ

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

OAuth 2.0 authorization-code flow. The relevant scopes are crm.objects.custom.read and crm.objects.custom.write; specific custom object types may require additional standard-object scopes for associations. Through Jentic the OAuth refresh token is stored in your Jentic One instance.

### Can I batch upsert custom object records?

Yes. POST `/crm/v3/objects/{objectType}/batch/upsert` accepts up to 100 records keyed by a unique property. The response includes per-record status so partial failures can be retried without resending the entire batch.

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

HubSpot applies tier-based rate limits across all CRM v3 endpoints (typically 100 requests / 10 seconds for the CRM v3 surface). The exact ceiling depends on your subscription and is documented in the HubSpot developer rate-limits page; the OpenAPI spec does not encode it.

### Do I need HubSpot Enterprise to use this API?

Yes. The custom object record endpoints require HubSpot Enterprise. Without Enterprise the API responds with a 403, and the linked CRM Schemas API will not let you define new object types.

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

Use the Jentic search query 'search HubSpot custom object records', which resolves to POST `/crm/v3/objects/{objectType}/search.` Provide the objectType and a filterGroups array, and Jentic injects the OAuth token automatically.

### How do I associate a custom object record with a contact or deal?

Call PUT `/crm/v3/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}.` The 'default' association uses HubSpot's standard association type so you do not have to look up labelled association type IDs first.

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

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. Since HubSpot puts the object type and record id in the URL path (`/crm/v3/objects/{objectType}/{objectId}`), you can pin the agent to reading and updating records of a single object type and nothing else. You choose the exact operations it may call, so higher-impact actions like a batch write or a record merge are excluded unless you add them.