canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-appointments

# HubSpot Appointments

The HubSpot Appointments API exposes the appointment object inside HubSpot CRM as a generic object resource. It supports listing, creating, updating, archiving, batch operations, and search across appointment records, mirroring the standard HubSpot CRM object shape with custom property maps. Use this API to read or mutate appointment objects programmatically alongside contacts, deals, and other CRM resources.

## For AI agents

Create, read, update, and search HubSpot CRM appointment objects, including batch and upsert operations. Useful for agents synchronising appointments between HubSpot and another scheduling system.

## Scope

Does not send calendar invites, manage availability, or render booking pages - use for HubSpot CRM appointment object operations only.

## Capabilities

- Create individual or batched appointment records with custom properties
- Update appointments by internal ID or unique property values
- Archive appointments individually or in batches
- Search appointments using HubSpot's CRM search filters and sorts
- Upsert a batch of appointments by unique property to avoid duplicates
- Read appointments by ID or by unique property in a batch read
- Page through the full list of appointment records

## Use cases

### Calendar Sync into HubSpot

Import a stream of new and updated appointments from an external scheduling tool into HubSpot CRM. The Appointments API exposes batch upsert keyed on a unique property, so the agent can re-run the sync idempotently without creating duplicate records.

Example prompt: POST /crm/v3/objects/{objectType}/batch/upsert with objectType=appointments and a list of appointment payloads keyed by an external ID property.

### Pipeline Reporting on Meetings

Query appointment records associated with a sales pipeline to compute meeting volume, no-show rates, or rep coverage. Search supports filters and sorts so the agent can pull only the appointments matching the report's criteria, paginated.

Example prompt: POST /crm/v3/objects/{objectType}/search with objectType=appointments and a filter on hs_appointment_start within the reporting window.

### Cancellation and Rescheduling Workflow

When a customer cancels via an external portal, archive the matching HubSpot appointment and create a replacement record for the rescheduled time. The API supports both archive and create as single calls or as part of a batch, suitable for high-volume scheduling integrations.

Example prompt: DELETE /crm/v3/objects/{objectType}/{objectId} for the cancelled appointment, then POST /crm/v3/objects/{objectType} to create the rescheduled record.

### Agent-Driven Appointment Operations

Wire HubSpot appointment management into an AI scheduling assistant via Jentic. The agent searches by intent for the right operation, loads the input schema, and executes - no HubSpot client code required, and credentials stay in your Jentic One instance.

Example prompt: Use Jentic search 'create a HubSpot appointment record', load the POST /crm/v3/objects/{objectType} schema with objectType=appointments, and execute with the appointment payload.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /crm/v3/objects/{objectType} | List appointment objects |
| POST | /crm/v3/objects/{objectType} | Create an appointment |
| GET | /crm/v3/objects/{objectType}/{objectId} | Read an appointment by ID |
| PATCH | /crm/v3/objects/{objectType}/{objectId} | Update an appointment |
| DELETE | /crm/v3/objects/{objectType}/{objectId} | Archive an appointment |
| POST | /crm/v3/objects/{objectType}/batch/upsert | Upsert a batch of appointments |
| POST | /crm/v3/objects/{objectType}/search | Search appointments |

## Key resources

- **Appointments** — Appointment object CRUD, batch operations, and search under /crm/v3/objects/{objectType}.

## Why Jentic

- **Setup:** Wiring HubSpot Appointments by hand means registering an OAuth app or minting a private app token, targeting api.hubapi.com, and coding the CRM object create, patch, upsert, and search calls plus paging yourself. Through Jentic you install once, import Appointments from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Appointments puts the object id in the URL path (/crm/v3/objects/{objectType}/{objectId}), so a rule can pin your agent to reading or updating one appointment record. You choose the operations it may call, so deleting an appointment is not included unless you add it.
- **Credential handling:** Your HubSpot OAuth token or private app 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 HubSpot appointment' or 'search appointments', and Jentic returns the matching Appointments operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Meetings** — Manage meeting engagement records on contacts and deals.
- **HubSpot CRM Contacts** — Resolve and update the contacts that appointments are scheduled with.
- **HubSpot CRM Associations** — Associate appointments with contacts, deals, or companies.

## FAQ

### What authentication does the HubSpot Appointments API use?

OAuth 2.0 authorization code flow or a private app token in either the `private-app` or `private-app-legacy` header. Through Jentic, the credential lives encrypted in the vault and the agent only ever sees a scoped execution token.

### Can I upsert appointments to avoid duplicate records?

Yes. POST /crm/v3/objects/{objectType}/batch/upsert with objectType=appointments accepts a unique property key - HubSpot creates new records or updates existing ones based on that key, which is the right pattern for idempotent calendar syncs.

### What are the rate limits for the Appointments API?

Standard HubSpot CRM API limits apply - 100 requests per 10 seconds per OAuth app, with daily caps on most paid tiers. Use batch read, batch upsert, and batch update endpoints to stay well within limits during bulk syncs.

### How do I search HubSpot appointments by date through Jentic?

Search Jentic for `search HubSpot appointments`, load the POST /crm/v3/objects/{objectType}/search schema with objectType=appointments, and execute with a filter on the appointment start date property. Install with `pip install jentic` and authenticate using `JENTIC_AGENT_API_KEY`.

### Does this API expose default appointment properties?

Yes. As with other HubSpot CRM objects, the appointment endpoints return a property map per record. You can also pass an explicit `properties` query parameter on read calls to control which properties HubSpot returns.

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

Yes. Because you run Jentic One yourself, your own rules decide which Appointments operations the agent may call, so you can allow reading and searching appointment records while withholding create, update, upsert, or archive. Since each appointment carries its object id in the URL path (/crm/v3/objects/{objectType}/{objectId}), a rule can pin the agent to reading or updating a single appointment record. Archiving an appointment via DELETE is not available to the agent unless you explicitly add that operation, and your HubSpot token stays under your control rather than in the agent's context.