canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-public-app-cards

# HubSpot Public App Crm Cards

The HubSpot Public App CRM Cards API lets a public HubSpot app declare and manage the custom cards it surfaces in the sidebar of CRM record pages. Each card is registered up-front against an app ID with a target object type, a fetch URL HubSpot calls when a record is opened, and a definition of the actions and properties to render. Endpoints cover create, read, update, and delete of cards under a given app, plus a sample response endpoint that returns a representative payload so app developers can build a matching fetch handler. Use it to build product integrations that show external data - open invoices, ticket counts, account health - directly inside the HubSpot CRM UI.

## For AI agents

Register and manage the custom CRM cards that a HubSpot public app surfaces on contact, company, deal, and ticket record pages.

## Scope

Does not render the card UI itself, host the fetch handler, or manage app installation - use for declaring HubSpot CRM card definitions on a public app only.

## Capabilities

- Register a new CRM card definition under a public app ID
- Read a single CRM card definition by app and card ID
- Update a card's fetch URL, target object type, or property layout
- Delete a card definition that is no longer in use
- List every CRM card defined for a given app
- Retrieve a sample fetch response payload to scaffold a card handler

## Use cases

### Register a CRM sidebar card

Register a new card so a public HubSpot app can render data inside the sidebar of contact, company, deal, or ticket record pages. POST /crm/v3/extensions/cards-dev/{appId} with the card's title, target object types, fetch URL, and property layout. HubSpot calls the fetch URL each time a record is opened and renders the response.

Example prompt: POST /crm/v3/extensions/cards-dev/{appId} with title='Account Health', objectTypes=[contacts], fetch.targetUrl set to a public endpoint, and a properties layout.

### Card lifecycle management

Manage cards across a release cycle: list every card on the app, update fetch URLs after a deployment, and delete cards that have been retired. GET, PATCH, and DELETE under /crm/v3/extensions/cards-dev/{appId}/{cardId} provide the per-card operations and GET on /crm/v3/extensions/cards-dev/{appId} returns the full set.

Example prompt: PATCH /crm/v3/extensions/cards-dev/{appId}/{cardId} setting fetch.targetUrl to the new staging URL, then GET to verify the update applied.

### Bootstrap a card handler from sample response

Use the sample response endpoint to scaffold a card fetch handler. GET /crm/v3/extensions/cards-dev/sample-response returns a representative payload that the app's backend can mimic when responding to HubSpot's card fetch calls, removing guesswork about the expected schema.

Example prompt: GET /crm/v3/extensions/cards-dev/sample-response and use the returned JSON as the contract for the app's card endpoint.

### AI agent execution through Jentic

An agent that needs to register or manage CRM cards for a public app discovers this API via Jentic's intent search using a query like 'register a hubspot crm card', loads the input schema for the chosen operation, and executes the call with credentials supplied from your Jentic One instance. The same flow handles list, update, delete, and sample lookups.

Example prompt: Search Jentic for 'register a hubspot crm card', load POST /crm/v3/extensions/cards-dev/{appId}, and execute it with a card definition payload.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /crm/v3/extensions/cards-dev/{appId} | List all CRM cards for an app |
| POST | /crm/v3/extensions/cards-dev/{appId} | Register a new CRM card under an app |
| GET | /crm/v3/extensions/cards-dev/{appId}/{cardId} | Read a single card definition by ID |
| PATCH | /crm/v3/extensions/cards-dev/{appId}/{cardId} | Update a card's fetch URL or layout |
| DELETE | /crm/v3/extensions/cards-dev/{appId}/{cardId} | Delete a card definition |
| GET | /crm/v3/extensions/cards-dev/sample-response | Retrieve a sample fetch response payload |

## Key resources

- **Cards** — Create, read, update, delete, and list CRM cards under a public app ID
- **SampleResponse** — Return a sample fetch response payload to scaffold card handlers

## Why Jentic

- **Setup:** Wiring Public App Crm Cards by hand means managing your HubSpot developer hapikey, appending it as a query parameter on every call to api.hubapi.com, and building the card definition payloads yourself. Through Jentic you install once, import Public App Crm Cards from the API Directory, store the developer hapikey once, and your agent calls it.
- **Permission scoping:** This API puts the app id in the URL path (/crm/v3/extensions/cards-dev/{appId}/...), so a rule can pin your agent to one public app: it can read and register cards for that app and no other. You choose the operations it may call, so a destructive one like card deletion is not included unless you add it.
- **Credential handling:** Your HubSpot developer hapikey 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' or 'list app cards', and Jentic returns the matching Cards operation with its input schema, including the appId path parameter and card definition shape, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Objects** — Reads the records that cards render against in the sidebar
- **HubSpot CRM Properties** — Manages the properties cards can include in their fetch payload
- **HubSpot CRM Objects** — Generic CRM record API for embedding HubSpot data in external UIs instead of in-app cards

## FAQ

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

It requires a HubSpot developer API key (hapikey) - the developer-account credential rather than a per-portal OAuth token, because card definitions live at the public app level. Through Jentic, the developer key is stored encrypted in the credential vault and attached at request time.

### Can I create cards for any object type?

You declare the target object types in the card definition's objectTypes array. Standard CRM objects - contacts, companies, deals, tickets - are supported, plus any custom object configured for sidebar rendering on the portal.

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

Card management is governed by the developer-account-level rate limits (typically 100 requests per 10 seconds). The runtime fetch URL HubSpot calls per record view is subject to its own per-portal limits and timeouts.

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

Search Jentic with 'register a hubspot crm card', load POST /crm/v3/extensions/cards-dev/{appId}, and execute with the card payload. Jentic returns the new card ID; store it so you can PATCH or DELETE the card later.

### Is the HubSpot CRM Cards API free?

It is part of HubSpot's developer programme and free to call. The cards themselves only render for portals that have installed the public app, and HubSpot's app submission process applies before broad distribution.

### What does HubSpot send to my fetch URL?

When a record is opened, HubSpot POSTs a payload containing the portal ID, object type, object ID, and request signature to the URL configured on the card. GET /crm/v3/extensions/cards-dev/sample-response returns a representative payload to scaffold the handler against.

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

Yes. Because you run Jentic One yourself, your own rules decide which of this API's operations the agent may call and which HubSpot developer credential it uses. You can grant only the read and register operations (GET and POST on /crm/v3/extensions/cards-dev/{appId}) and withhold destructive ones like DELETE, and since the app id sits in the URL path you can pin the agent to a single public app so it cannot touch cards under any other. The developer key is supplied at execution time by your instance, not exposed to the agent.