Meetings

Please note: This API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer TermsDeveloper Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API. For the latest stable version of the engagements API, check out the legacy engagements overview.

Use the meetings engagement API to log and manage meetings on CRM records. You can log meeting activities either in HubSpot or through the meetings API. You can retrieve, update, or delete meeting engagements that are manually logged on a record, scheduled using the meetings tool, or scheduled using the Google Calendar or Office 365 calendar integration.

Below, learn the basic methods of managing meetings through the API. To view all available endpoints and their requirements, click the Endpoints tab at the top of this article.

Create a meeting engagement

To create a meeting engagement, make a POST request to /crm/v3/objects/meetings.

In the request body, add meeting details in a properties object, which can contain the following fields:

Use this table to describe parameters / fields
FieldDescription
hs_timestamp

Required. This field marks the meeting's time of creation and determines where the meeting sits on the record timeline. You can use either a Unix timestamp in milliseconds or UTC format. 

hs_meeting_title

The title of the meeting.

hubspot_owner_id

The ID of the owner associated with the meeting. This field determines the user listed as the meeting creator on the record timeline.

hs_meeting_body

The meeting description. 

hs_internal_meeting_notes

The internal notes you take for your team during a meeting that are not included in the attendee meeting description. 

hs_meeting_external_URL

The external URL for the calendar event. For example, this could be a Google calendar link or a Microsoft Outlook calendar link.

hs_meeting_location

Where the meeting takes place. The value could be a physical address, a conference room, a videoconference link, or a phone number. This appears on the calendar invite on the attendee's calendar. 

hs_meeting_start_time

The date and time when the meeting starts. 

hs_meeting_end_time

The date and time when the meeting ends. 

hs_meeting_outcome

The outcome of the meeting. The outcome values are scheduled, completed, rescheduled, no show, and canceled. 

For example, your request body might look similar to the following:

JSON
// Example request body
{
  "properties": {
    "hs_timestamp": "2019-10-30T03:30:17.883Z",
    "hubspot_owner_id": "11349275740",
    "hs_meeting_title": "Intro meeting",
    "hs_meeting_body": "The first meeting to discuss options",
    "hs_internal_meeting_notes": "These are the meeting notes",
    "hs_meeting_external_url": 
    "https://Zoom.com/0000",
    "hs_meeting_location": "Remote",
    "hs_meeting_start_time": "2021-03-23T01:02:44.872Z",
    "hs_meeting_end_time": "2021-03-23T01:52:44.872Z",
    "hs_meeting_outcome": "SCHEDULED"
   }
}

Learn more about batch creating meetings by clicking the Endpoints tab at the top of this article.

Associate meetings with records

To associate a meeting with records, such as a contact and its associated companies, make a PUT request to /crm/v3/objects/meetings/{meetingId}/associations/{toObjectType}/{toObjectId}/{associationType}. The request URL contains the following fields:

Use this table to describe parameters / fields
FieldDescription
meetingId

The ID of the meeting.

toObjectType

The type of object that you want to associate the meeting with (e.g., contact or company)

toObjectId

The ID of the record that you want to associate the meeting with.

associationType

The ID of the association type between the meeting and the other object type. You can retrieve this value through the associations API.

For example, your request URL might look similar to the following:

https://api.hubspot.com/crm/v3/objects/meetings/17612479134/associations/contact/104901/200

Remove an association

To remove an association between a meeting and a record, make a DELETE request to the same URL as above:

/crm/v3/objects/meetings/{meetingId}/associations/{toObjectType}

Retrieve meetings

You can retrieve meetings individually or in bulk. Learn more about batch retrieval by clicking the Endpoints tab at the top of this article.

To retrieve an individual meeting by its meeting ID, make a GET request to /crm/v3/objects/meetings/{meetingId}. You can also include the following parameters in the request URL: 

Use this table to describe parameters / fields
ParameterDescription
properties

A comma separated list of the properties to be returned. 

associations

A comma separated list of objects to you want to retrieve associated record IDs from. 

To request a list of all of meetings, make a GET request to crm/v3/objects/meetings. You can include the following parameters in the request URL: 

Use this table to describe parameters / fields
ParameterDescription
limit

The maximum number of results to display per page.

properties

A comma separated list of the properties to be returned. 

Update meetings

You can update meetings individually or in batches. To update an individual meeting by its meeting ID, make a PATCH request to /crm/v3/objects/meetings/{meetingId}

In the request body, include the meeting properties that you want to update. For example, your request body might look similar to the following:

JSON
//Example PATCH request to https://api.hubspot.com/crm/v3/objects/meetings/{meetingId}
{
  "properties": {
     "hs_timestamp": "2019-10-30T03:30:17.883Z",
     "hubspot_owner_id": "11349275740",
     "hs_meeting_title": "Intro meeting",
     "hs_meeting_body": "The first meeting to discuss options",
     "hs_internal_meeting_notes": "These are the meeting notes",
     "hs_meeting_external_url": 
     "https://Zoom.com/0000",
     "hs_meeting_location": "Remote",
     "hs_meeting_start_time": "2021-03-23T01:02:44.872Z",
     "hs_meeting_end_time": "2021-03-23T01:52:44.872Z",
     "hs_meeting_outcome": "SCHEDULED"
  }
}'

HubSpot will ignore values for read-only and non-existent properties. To clear a property value, pass an empty string for the property in the request body.

Learn more about batch updating by clicking the Endpoints tab at the top of this article.

Delete meetings

You can delete meetings individually or in batches, which will add the meeting to the recycling bin in HubSpot. You can later restore the meeting from the record timeline.

To delete an individual meeting by its meeting ID, make a DELETE request to /crm/v3/objects/meetings/{meetingId}.

Learn more about batch deleting by clicking the Endpoints tab at the top of this article.


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.