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

# HubSpot CRM Schemas

The HubSpot CRM Schemas API defines the structure of custom objects in HubSpot's CRM on the EU region. Schemas declare an object's type, its properties (fields) and its associations to other CRM objects, and each schema is identified by a unique objectTypeId. Use this API to design new custom object types or evolve existing ones; record-level operations live in the separate CRM Custom Objects API.

## For AI agents

Create, retrieve, update and delete HubSpot custom object schemas, and define associations between schema types on the EU region.

## Scope

Does not manage record-level data, contacts, or marketing automation - use for defining custom object schemas and their associations only.

## Capabilities

- Define a new custom object schema with name, properties and primary display fields
- Retrieve every custom object schema configured on the account
- Update an existing schema to add new properties or change associations
- Delete a custom object schema that is no longer in use
- Create an association between two custom object types so records can be linked
- Remove an association between two schemas

## Use cases

### Custom object schema design

Define a new custom object type such as Subscription with a controlled set of properties and a primary display property before any records exist. POST `/crm-object-schemas/v3/schemas` accepts the name, labels, requiredProperties and primaryDisplayProperty, and HubSpot returns the objectTypeId used by the Custom Objects API. Schema design is a one-time set-up activity per object type.

Example prompt: POST `/crm-object-schemas/v3/schemas` with name 'subscription', a labels block, requiredProperties for plan_tier and start_date, then capture the returned objectTypeId.

### Schema audit and inventory

Inventory every custom object schema in the account so administrators know which types exist and what properties they expose. GET `/crm-object-schemas/v3/schemas` returns an array of schema definitions which can be exported as documentation for downstream teams.

Example prompt: GET `/crm-object-schemas/v3/schemas`, then write each schema's name, objectTypeId and property list into a CSV for the data team.

### Schema evolution

Add or rename properties on an existing schema as the business model evolves. PATCH `/crm-object-schemas/v3/schemas/{objectType}` updates the schema in place; properties cannot be deleted but can be archived, so plan the rollout carefully.

Example prompt: PATCH `/crm-object-schemas/v3/schemas/{objectType}` adding a new property definition, then verify it appears in the GET response.

### Cross-schema associations

Connect two custom object types so HubSpot records can be linked together (for example, a Vehicle to a Service Visit). POST `/crm-object-schemas/v3/schemas/{objectType}/associations` defines a typed association which is then usable from the Custom Objects associations endpoints.

Example prompt: POST `/crm-object-schemas/v3/schemas/vehicle/associations` with toObjectTypeId of the service_visit schema and a name 'vehicle_to_service_visit'.

### Agent-driven schema bootstrap via Jentic

An AI agent provisioning a new HubSpot environment reads a schema definition from a YAML file and uses the Schemas API through Jentic to create each custom object type and its associations in order. Jentic isolates the OAuth credentials and resolves the right endpoint per intent.

Example prompt: Search Jentic for 'create a HubSpot custom object schema', load the schema for POST `/crm-object-schemas/v3/schemas`, and execute for each entry in the YAML.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/crm-object-schemas/v3/schemas` | List all custom object schemas |
| POST | `/crm-object-schemas/v3/schemas` | Create a new schema |
| GET | `/crm-object-schemas/v3/schemas/{objectType}` | Read a single schema |
| PATCH | `/crm-object-schemas/v3/schemas/{objectType}` | Update a schema |
| DELETE | `/crm-object-schemas/v3/schemas/{objectType}` | Delete a schema |
| POST | `/crm-object-schemas/v3/schemas/{objectType}/associations` | Create an association definition |
| DELETE | `/crm-object-schemas/v3/schemas/{objectType}/associations/{associationIdentifier}` | Remove an association |

## Key resources

- **Core** — Schema and association definitions for HubSpot custom object types

## Why Jentic

- **Setup:** Wiring HubSpot CRM Schemas by hand means running its OAuth2 flow, refreshing tokens against the api.hubapi.com host, and shaping the requiredProperties and label payloads for schema definitions yourself. Through Jentic you install once, import HubSpot CRM Schemas from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** HubSpot puts the object type in the URL path (`/crm-object-schemas/v3/schemas/{objectType}`), so a rule can pin your agent to reading or updating one object type's schema and nothing else. You choose the operations it may call, so DELETE `/schemas/{objectType}` is not included unless you add it.
- **Credential handling:** Your HubSpot OAuth 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 'define a HubSpot custom object schema', and Jentic returns the matching POST `/crm-object-schemas/v3/schemas` operation with its requiredProperties and labels schema so the agent calls the right endpoint without interpreting the schema-modelling reference manually.

## Related APIs

- **HubSpot CRM Custom Objects** — Manages records for the schemas defined by this API
- **Salesforce API** — Salesforce custom object metadata is managed via the Metadata API for similar schema-design needs
- **Zoho CRM API** — Zoho CRM modules and fields offer comparable custom data modelling

## FAQ

### What authentication does the HubSpot CRM Schemas API use?

OAuth 2.0 authorization-code flow. The required scopes are crm.schemas.custom.read and crm.schemas.custom.write. Through Jentic the refresh token is stored in your Jentic One instance and a scoped access token is injected per call.

### Can I delete a custom object schema with this API?

Yes. DELETE `/crm-object-schemas/v3/schemas/{objectType}` removes the schema, but only if no records of that type exist. Archive or delete the records via the Custom Objects API first.

### How do I add a new property to an existing schema?

Call PATCH `/crm-object-schemas/v3/schemas/{objectType}` with a properties array containing the new field. HubSpot does not allow property deletion, only archiving, so design the field set carefully before the schema is live.

### What are the rate limits for the HubSpot CRM Schemas API?

Schema operations are administrative and share the standard HubSpot CRM v3 rate limits, which depend on subscription tier. The OpenAPI spec does not encode the exact ceiling - watch for 429 responses in production.

### How do I create a schema through Jentic?

Use the Jentic search query 'create a HubSpot custom object schema', which resolves to POST `/crm-object-schemas/v3/schemas.` Run pip install jentic, load the operation, and execute with the schema definition.

### Do I need HubSpot Enterprise to use the Schemas API?

Yes. Custom object schema management requires HubSpot Enterprise. Lower tiers can read schemas for the standard objects but cannot create new custom object types.

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

Yes. Jentic One is self-hosted by you, so your own rules decide which schema operations the agent may call and which HubSpot credentials it may use. Because the object type sits in the URL path (`/crm-object-schemas/v3/schemas/{objectType}`), you can pin the agent to reading or updating a single object type's schema and nothing else. You choose the exact operations it can reach, so a destructive call like DELETE `/crm-object-schemas/v3/schemas/{objectType}` stays out of scope unless you explicitly add it.