> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 1ecdcc2a-6b62-4402-b4b6-645f3ee0d53d
---
# Activities | Meetings
> Use the meetings engagement API to log and manage meetings on CRM records.
export const PostmanCard = ({title, collectionId}) => {
return
} />
;
};
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
Use the meetings engagement API to log and manage meetings on CRM records. You can log meeting activities either [in HubSpot](https://knowledge.hubspot.com/records/manually-log-activities-on-records) 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](https://knowledge.hubspot.com/meetings-tool/use-meetings), or [scheduled using the Google Calendar or Office 365 calendar integration](https://knowledge.hubspot.com/meetings-tool/schedule-a-meeting-on-a-record).
## Create a meeting
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. You can also add an **associations** object to associate your new meeting with an existing record (e.g., contacts, companies).
### Properties
In the properties object, you can include the following fields:
| Field | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hs_timestamp` | Required. This field marks the date and time that the meeting occurred. You can use either a Unix timestamp in milliseconds or UTC format. When the property value is missing, the value will default to `hs_meeting_start_time.` |
| `hs_meeting_title` | The title of the meeting. |
| `hubspot_owner_id` | The [ID of the owner](/api-reference/legacy/crm/owners/guide) 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. The value for this property should match the value for `hs_timestamp`. |
| `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. |
| `hs_activity_type` | The type of meeting. The options are based on the [meeting types set in your HubSpot account.](https://knowledge.hubspot.com/meetings-tool/how-do-i-create-and-use-call-and-meeting-types) |
| `hs_attachment_ids` | The IDs of the meeting's attachments. Multiple attachment IDs are separated by a semi-colon. |
### Associations
To create and associate a meeting with existing records, include an associations object in your request. For example, to create and associate a meeting with contacts, your request may look similar to the following:
```json theme={null}
{
"properties": {
"hs_timestamp": "2021-03-23T01:02:44.872Z",
"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"
},
"associations": [
{
"to": {
"id": 101
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 200
}
]
},
{
"to": {
"id": 102
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 200
}
]
}
]
}
```
The associations object should include:
| Field | Description |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | The record you want to associate with the meeting, specified by its unique `id` value. |
| `types` | The type of the association between the meeting and the record. Include the `associationCategory`and `associationTypeId`. Default association type IDs are listed [here](/api-reference/legacy/crm/associations/v3/associate-records#association-type-id-values), or you can retrieve the value for custom association types (i.e. labels) via the [associations API](/api-reference/legacy/crm/associations/v3/associate-records#retrieve-association-types). |
Learn more about batch creating meetings by checking out the [reference documentation](/api-reference/legacy/crm/activities/meetings/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fmeetings%2Fbatch%2Fcreate).
## Retrieve meetings
You can retrieve meetings individually or in bulk. Learn more about batch retrieval by checking out the [reference documentation](/api-reference/legacy/crm/activities/meetings/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fmeetings%2Fbatch%2Fread).
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:
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | A comma separated list of the properties to be returned. If a requested property isn't defined, it won't be included in the response. If a requested property is defined but a meeting doesn't have a value, it will be returned as `null`. |
| `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:
| Parameter | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | The maximum number of results to display per page. |
| `properties` | A comma separated list of the properties to be returned. If a requested property isn't defined, it won't be included in the response. If a requested property is defined but a meeting doesn't have a value, it will be returned as `null`. |
## 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 theme={null}
{
"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 checking out the [reference documentation](/api-reference/legacy/crm/activities/meetings/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fmeetings%2Fbatch%2Fupdate).
### Associate existing 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}/{associationTypeId}`. The request URL contains the following fields:
| Field | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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. |
| `associationTypeId` | The ID of the association type between the meeting and the other object type. You can retrieve this value through the [associations API](/api-reference/legacy/crm/associations/v3/associate-records). |
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}/{toObjectId}/{associationTypeId}`
## Pin a meeting on a record
You can [pin a meeting](https://knowledge.hubspot.com/records/pin-an-activity-on-a-record) on a record so it remains on the top of the record's timeline. The meeting must already be associated with the record prior to pinning, and you can only pin one activity per record. To pin a meeting, include the meeting's `id` in the `hs_pinned_engagement_id` field when creating or updating a record via the object APIs. Learn more about using the [companies](/api-reference/legacy/crm/objects/companies/guide#pin-an-activity-on-a-company-record), [contacts](/api-reference/legacy/crm/objects/contacts/guide#pin-an-activity-on-a-contact-record), [deals](/api-reference/legacy/crm/objects/deals/guide#pin-an-activity-on-a-deal-record), [tickets](/api-reference/legacy/crm/objects/tickets/guide#pin-an-activity-on-a-ticket-record), and [custom objects](/api-reference/legacy/crm/objects/custom-objects/guide) APIs.
## 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.](https://knowledge.hubspot.com/records/restore-deleted-activity-in-a-record)
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 checking out the [reference documentation](/api-reference/legacy/crm/activities/meetings/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fmeetings%2F%7Bmeetingid%7D).