CRM API | Appointments - HubSpot docs

Scope requirements

In HubSpot, appointments store information about scheduled appointments. The appointments endpoints allow you to create and manage appointment records in your HubSpot account, as well as sync appointment data between HubSpot and other systems. The appointment object must be activated in the HubSpot account to manage appointment records. Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide.

Create appointments

To create new appointments:

To create one appointment, make a POST request to /crm/objects/2026-03/appointments.
To create multiple appointments, make a POST request to /crm/objects/2026-03/appointments/batch/create.

In your request, include your appointment data in a properties object. You can also add an associations object to associate your new appointment with existing records (e.g., contacts, companies), or activities (e.g., meetings, notes).

For batch create actions, you can enable multi-status errors which tell you which records were successfully created and which were not. Learn more about setting up multi-status error handling.

Create appointments with property values

When creating an appointment, include appointment properties to store the appointment’s details. For example, to create a new appointment, your request may look similar to the following:

{
  "properties": {
    "hs_appointment_name": "Annual checkup",
    "hs_appointment_start": "2026-06-01T09:00:00Z",
    "hs_appointment_end": "2026-06-01T10:00:00Z",
    "hs_appointment_status": "SCHEDULED"
  }
}

For a list of default appointment properties, refer to the appointments object definition page. To view all available appointment properties in your account, including custom properties, make a GET request to /crm/properties/2026-03/appointments. Learn more about the properties API.

Create appointments with associations

When creating a new appointment, you can also associate the appointment with existing records or activities by including an associations array. For example, to associate a new appointment with an existing contact, your request would look like the following:

{
  "properties": {
    "hs_appointment_name": "Annual checkup",
    "hs_appointment_start": "2026-06-01T09:00:00Z",
    "hs_appointment_end": "2026-06-01T10:00:00Z"
  },
  "associations": [
    {
      "to": {
        "id": "123456"
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 578
        }
      ]
    }
  ]
}

Parameter	Description
`to`	The record or activity you want to associate with the appointment, specified by its unique `id` value.
`types`	The type of the association between the appointment and the record/activity. Include the `associationCategory` and `associationTypeId`. Default association type IDs are listed on the associations API guide, or you can retrieve the value for custom association types via the associations API.

Retrieve appointments

You can retrieve appointments individually or in batches. Include the following query parameters in your request URLs to retrieve certain data.

Parameter	Description
`properties`	A comma-separated list of the properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but an appointment doesn’t have a value, it will be returned as `null`.
`propertiesWithHistory`	A comma-separated list of the current and historical properties to be returned in the response.
`associations`	Supported when retrieving an individual appointment or all appointments, a comma-separated list of objects to retrieve associated IDs for. Learn more about the associations API.

Retrieve an individual appointment

To retrieve an individual appointment by its record ID, make a GET request to /crm/objects/2026-03/appointments/{appointmentId}.

Retrieve all appointments

To request a list of all appointments, make a GET request to /crm/objects/2026-03/appointments. You can retrieve up to 100 appointments in one request.

To retrieve a specific amount under 100, add a value to the limit parameter. For example, ?limit=50.
To paginate through results, include the after parameter with the after value returned from the previous request.

Retrieve a batch of appointments

To retrieve appointments in batches, make a POST request to /crm/objects/2026-03/appointments/batch/read. Include the id values of the appointments you want to retrieve.

Please note: the batch endpoint cannot retrieve associations. To view associations for a specific batch of appointments, retrieve the appointments’ id values first, then include them in a request to the batch read associations API endpoint. Learn how to retrieve associations with the associations API.

For example, to retrieve a batch of appointments by their record ID values:

{
  "properties": ["hs_appointment_name", "hs_appointment_start", "hs_appointment_end"],
  "inputs": [
    {
      "id": "1234567"
    },
    {
      "id": "987456"
    }
  ]
}

Update appointments

You can update appointments individually or in batches.

Update an individual appointment

To update an individual appointment by its record ID, make a PATCH request to /crm/objects/2026-03/appointments/{appointmentId}, and include the data you want to update. For example:

{
  "properties": {
    "hs_appointment_status": "COMPLETED"
  }
}

Update a batch of appointments

To update multiple appointments, make a POST request to /crm/objects/2026-03/appointments/batch/update. In your request body, include each appointment’s record ID as the id and include the properties you want to update. For example:

{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "hs_appointment_status": "COMPLETED"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "hs_appointment_status": "CANCELLED"
      }
    }
  ]
}

Upsert appointments

You can batch create and update appointments at the same time using the upsert endpoint. Following the request, if the appointments already exist, they’ll be updated; if they don’t exist, they’ll be created. To upsert appointments, make a POST request to /crm/objects/2026-03/appointments/batch/upsert.

Associate existing appointments with records or activities

To associate an appointment with other CRM records or an activity, make a PUT request to /crm/objects/2026-03/appointments/{appointmentId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

To retrieve the associationTypeId value, refer to the list of default values, or make a GET request to /crm/associations/2026-03/{fromObjectType}/{toObjectType}/labels.

Learn more about the associations API.

Delete appointments

You can delete appointments individually or in batches, which will add the appointment to the recycling bin in HubSpot. You can later restore the record within HubSpot.

To delete an individual appointment, make a DELETE request to /crm/objects/2026-03/appointments/{appointmentId}.
To delete appointments in batches, make a POST request to /crm/objects/2026-03/appointments/batch/archive.

​Create appointments

​Create appointments with property values

​Create appointments with associations

​Retrieve appointments

​Retrieve an individual appointment

​Retrieve all appointments

​Retrieve a batch of appointments

​Update appointments

​Update an individual appointment

​Update a batch of appointments

​Upsert appointments

​Associate existing appointments with records or activities

​Delete appointments

Create appointments

Create appointments with property values

Create appointments with associations

Retrieve appointments

Retrieve an individual appointment

Retrieve all appointments

Retrieve a batch of appointments

Update appointments

Update an individual appointment

Update a batch of appointments

Upsert appointments

Associate existing appointments with records or activities

Delete appointments