canonical: https://jentic.com/apis/hubapi.com/hubspot-crm-api

# HubSpot CRM cards

Jentic publishes the only available OpenAPI specification for HubSpot CRM Cards, keeping it validated and agent-ready. The CRM Cards API lets a HubSpot app extend the CRM UI by surfacing custom cards in the sidebar of contact, company, deal, and ticket record pages. Apps register card definitions up front, including the data fetch URL HubSpot calls when a record loads. The card definitions, sample-response shape, and per-app card list are all managed through this API.

## For AI agents

Register and manage custom CRM sidebar cards for a HubSpot app so external data is surfaced inside the HubSpot record UI.

## Scope

Does not handle CRM contact, company, deal, or ticket CRUD - use for registering CRM sidebar card extensions only.

## Capabilities

- Register a custom CRM card definition for a HubSpot app
- Update card metadata such as title, fetch URL, and target object types
- Delete a card definition that is no longer in use
- Retrieve a sample card response to validate card rendering
- List every CRM card configured for an installed app
- Configure which CRM record types a card appears on

## Use cases

### External Data on CRM Records

Many sales teams want to see external data - billing status, support tickets in another system, product usage scores - directly on the HubSpot contact or company record. The CRM Cards API registers a card definition that points HubSpot at a fetch URL on your service. When a CRM user opens the record, HubSpot calls the URL and renders the response as a card in the sidebar.

Example prompt: Create a card definition for app 12345 with title 'Account Health', fetch URL https://example.com/hubspot/cards/account-health, and target object types CONTACT and COMPANY

### Card Definition Lifecycle

As an integration evolves, card titles, fetch URLs, and target object types change. The PATCH endpoint updates the definition in place; the DELETE endpoint removes it when the card is retired. The list endpoint provides the inventory used by deployment scripts and by the app's own admin UI.

Example prompt: List all card definitions for app 12345, find the card with title 'Legacy Health Score', and DELETE it

### Card Response Validation

Before deploying a new card, developers run the sample-response endpoint to see exactly what payload shape HubSpot expects. This avoids the trial-and-error loop of installing the app, opening a record, and inspecting failed renderings. The sample is canonical, so engineering can mock it in tests.

Example prompt: Call GET /crm/v3/extensions/cards/sample-response and return the exact card payload schema for use as a test fixture

### Agent-Driven Card Provisioning

An AI agent that owns a HubSpot app's deployment process uses Jentic to register and update CRM cards as part of release automation. It searches for 'register hubspot crm card', loads the schema, and posts the new definition. Subsequent runs detect drift and PATCH the definition to match.

Example prompt: Search Jentic for 'register hubspot crm card', load the schema, and create or update the card definition for the current app to match the desired-state config

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /crm/v3/extensions/cards/{appId} | Create a CRM card definition |
| GET | /crm/v3/extensions/cards/{appId} | List card definitions for an app |
| GET | /crm/v3/extensions/cards/{appId}/{cardId} | Get a single card definition |
| PATCH | /crm/v3/extensions/cards/{appId}/{cardId} | Update a card definition |
| DELETE | /crm/v3/extensions/cards/{appId}/{cardId} | Delete a card definition |
| GET | /crm/v3/extensions/cards/sample-response | Retrieve a canonical sample card response payload |

## Key resources

- **Card Definitions** — Register, list, update, and delete CRM sidebar cards for a HubSpot app
- **Sample Response** — Retrieve the canonical sample payload shape for a CRM card

## Why Jentic

- **Setup:** Wiring the HubSpot CRM Cards API by hand means holding a developer key, tracking the app and card ids across api.hubapi.com, and shaping the card definition payload yourself. Through Jentic you install once, import CRM Cards from the API Directory, store the developer key once, and your agent calls it.
- **Permission scoping:** HubSpot puts the app id in the URL path (/crm/v3/extensions/cards/{appId}), so a rule can pin your agent to one app: it registers and reads sidebar card definitions for that app and nothing else. You choose the operations it may call, so PATCH or DELETE on a card is not included unless you add it.
- **Credential handling:** Your HubSpot developer key 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 'register a hubspot crm card', and Jentic returns POST /crm/v3/extensions/cards/{appId} with its input schema, including the objectTypes and fetch URL fields, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Custom Workflow Actions** — Workflow actions extend automation while CRM cards extend the record UI
- **HubSpot Webhooks API** — Webhooks deliver record-change events that drive cached data shown in CRM cards
- **Salesforce REST API** — Salesforce Lightning Components are the equivalent extension surface in Salesforce CRM

## FAQ

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

HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call HubSpot CRM Cards 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 Cards API use?

It uses the developer hapikey passed as a query parameter on every request, scoped to the developer account that owns the app. Jentic stores the developer key in its encrypted vault and provides agents with a scoped token at execution time so the raw key never enters the agent's context.

### Can a CRM card appear on multiple object types?

Yes. The card definition body accepts an objectTypes array - for example ['CONTACT', 'COMPANY', 'DEAL', 'TICKET'] - and HubSpot renders the card on every record of those types. Update the array via PATCH /crm/v3/extensions/cards/{appId}/{cardId} when targeting changes.

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

Standard developer API limits apply: 100 requests per 10 seconds per developer account. Card definition operations are infrequent (typically deployment time only), so the limit rarely matters; the runtime fetch URL HubSpot calls is governed by your own service's capacity.

### How do I register a new CRM card through Jentic?

Search Jentic for 'register hubspot crm card', load the schema for POST /crm/v3/extensions/cards/{appId}, and execute with the card title, fetch URL, and objectTypes array. Use GET /crm/v3/extensions/cards/sample-response to confirm the payload shape your fetch URL must return.

### Is the HubSpot CRM Cards API free?

API access is included with HubSpot's developer programme, which is free to join. Cards render in any HubSpot portal that has installed the app, regardless of the portal's subscription tier.

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

Yes. Jentic One is self-hosted, so your own rules decide which operations and credentials the agent may use. Because HubSpot puts the app id in the URL path (/crm/v3/extensions/cards/{appId}), you can pin the agent to a single app so it only reads and registers sidebar card definitions for that app and nothing else. You also choose which operations it may call, so it can be limited to listing and creating cards while PATCH or DELETE on a definition stays out of reach unless you add it. The developer key that authenticates each request is held by your own instance and injected at execution time, never entering the agent's prompt or context.