> ## 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: bece340a-c46c-4ffc-86b3-1b4c8851fb43
---
# Create a new calendar event for a meeting
> Create a new calendar event and meeting object by providing the necessary details such as associations, email reminders, meeting object properties, and timezone.
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
;
};
## OpenAPI
````yaml specs/2026-03/scheduler-meetings-v2026-03.json POST /scheduler/2026-03/meetings/calendar
openapi: 3.0.1
info:
title: Scheduler Meetings
description: Meetings Service For HubSpot Sales
version: 2026-03
x-hubspot-product-tier-requirements:
marketing: FREE
sales: FREE
service: FREE
cms: FREE
commerce: FREE
crmHub: FREE
dataHub: FREE
servers:
- url: https://api.hubapi.com
security: []
tags:
- name: Advanced
- name: Basic
paths:
/scheduler/2026-03/meetings/calendar:
post:
tags:
- Advanced
summary: Create a new calendar meeting event.
description: >-
Create a new calendar event and meeting object by providing the
necessary details such as associations, email reminders, meeting object
properties, and timezone.
operationId: post-/scheduler/2026-03/meetings/calendar
parameters:
- name: organizerUserId
in: query
description: ''
required: true
style: form
explode: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalCalendarMeetingEventCreateRequest'
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalCalenderMeetingEventResponse'
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- crm.objects.contacts.highly_sensitive.write.v2
- oauth2:
- tickets
- oauth2:
- crm.objects.commercepayments.write
- oauth2:
- crm.objects.goals.write
- oauth2:
- crm.objects.line_items.write
- oauth2:
- crm.objects.contacts.write
- oauth2:
- crm.objects.products.write
- oauth2:
- crm.objects.projects.write
- oauth2:
- crm.objects.contacts.sensitive.write.v2
- oauth2:
- crm.objects.projects.sensitive.write
- oauth2:
- crm.objects.services.write
- oauth2:
- crm.objects.deals.sensitive.write.v2
- oauth2:
- tickets.highly_sensitive.v2
- oauth2:
- crm.objects.listings.write
- oauth2:
- crm.objects.appointments.sensitive.write.v2
- oauth2:
- crm.objects.companies.write
- oauth2:
- crm.objects.courses.write
- oauth2:
- crm.objects.appointments.write
- oauth2:
- tickets.sensitive.v2
- oauth2:
- crm.objects.deals.write
- oauth2:
- crm.objects.projects.highly_sensitive.write
- oauth2:
- crm.objects.companies.sensitive.write.v2
- oauth2:
- crm.objects.deals.highly_sensitive.write.v2
- oauth2:
- crm.objects.companies.highly_sensitive.write.v2
- oauth2:
- meetings-write
components:
schemas:
ExternalCalendarMeetingEventCreateRequest:
required:
- associations
- emailReminderSchedule
- properties
- timezone
type: object
properties:
associations:
type: array
items:
$ref: '#/components/schemas/ExternalAssociationCreateRequest'
emailReminderSchedule:
$ref: '#/components/schemas/ExternalEmailReminderSchedule'
properties:
$ref: '#/components/schemas/ExternalCalendarMeetingEventCreateProperties'
timezone:
type: string
description: The timezone property that will be set on the meeting event.
ExternalCalenderMeetingEventResponse:
required:
- createdAt
- id
- lastUpdatedAt
- properties
type: object
properties:
createdAt:
type: string
description: >-
The date and time when the meeting event was initially created, in
ISO 8601 format.
format: date-time
id:
type: string
description: The unique identifier for the meeting event.
lastUpdatedAt:
type: string
description: >-
The date and time when the meeting event was last updated, in ISO
8601 format.
format: date-time
properties:
$ref: '#/components/schemas/ExternalCalendarMeetingEventResponseProperties'
ExternalAssociationCreateRequest:
required:
- to
- types
type: object
properties:
to:
$ref: '#/components/schemas/PublicObjectId'
types:
type: array
items:
$ref: '#/components/schemas/AssociationSpec'
ExternalEmailReminderSchedule:
required:
- reminders
- shouldIncludeInviteDescription
type: object
properties:
reminders:
type: array
items:
$ref: '#/components/schemas/ExternalReminder'
shouldIncludeInviteDescription:
type: boolean
description: Whether the invite description should be included in the reminder.
ExternalCalendarMeetingEventCreateProperties:
required:
- hs_meeting_end_time
- hs_meeting_outcome
- hs_meeting_start_time
- hs_meeting_title
- hs_timestamp
- hubspot_owner_id
type: object
properties:
hs_activity_type:
type: string
description: >-
The activity type of the meeting. Acceptable values are based on
portal defined call and meeting types.
hs_attachment_ids:
type: array
items:
type: string
hs_attendee_owner_ids:
type: array
items:
type: string
hs_internal_meeting_notes:
type: string
description: Internal notes related to the meeting.
hs_meeting_body:
type: string
description: The description of the meeting and calendar event.
hs_meeting_end_time:
type: string
description: The time that the meeting should end in ISO 8601 format.
format: date-time
hs_meeting_location:
type: string
description: >-
The physical address, virtual location, or phone number where the
meeting will take place.
hs_meeting_location_type:
type: string
description: >-
The type of location for the meeting. Acceptable values are:
ADDRESS, CUSTOM, PHONE.
enum:
- ADDRESS
- CUSTOM
- PHONE
hs_meeting_outcome:
type: string
description: >-
The outcome of the meeting. Acceptable default values are:
SCHEDULED, COMPLETED, RESCHEDULED, NO_SHOW, CANCELED. This property
can be changed to include additional custom values.
hs_meeting_start_time:
type: string
description: The time that the meeting should start in ISO 8601 format.
format: date-time
hs_meeting_title:
type: string
description: The title of the meeting and calendar event.
hs_timestamp:
type: string
description: >-
The time that the meeting should start in ISO 8601 format. This
value should be the same as `hs_meeting_start_time`.
format: date-time
hubspot_owner_id:
type: string
description: The ownerId of the HubSpot user who will host the meeting.
ExternalCalendarMeetingEventResponseProperties:
required:
- hs_engagement_source
- hs_engagement_source_id
- hs_meeting_end_time
- hs_meeting_outcome
- hs_meeting_start_time
- hs_meeting_title
- hs_timestamp
type: object
properties:
hs_activity_type:
type: string
description: >-
The activity type of the meeting. Acceptable values are based on
portal defined call and meeting types.
hs_attachment_ids:
type: array
items:
type: string
hs_attendee_owner_ids:
type: array
items:
type: string
hs_engagement_source:
type: string
description: The source of the engagement, will always be `MEETINGS`.
enum:
- ACADEMY
- ACCEPTANCE_TEST
- ACTIVITY_AUTO_ASSOCIATE
- ACTIVITY_LOG_REVERT
- ADS
- AI_GROUP
- ANALYTICS
- API
- APPROVALS
- ASSISTS
- ASSOCIATIONS
- AUTO_ASSOCIATE_BY_DOMAIN
- AUTOMATION_JOURNEY
- AUTOMATION_PLATFORM
- AVATARS_SERVICE
- BATCH_UPDATE
- BCC_TO_CRM
- BEHAVIORAL_EVENTS
- BET_ASSIGNMENT
- BET_CRM_CONNECTOR
- BIDEN
- BILLING
- BOT
- BREEZE_AGENT
- CALCULATED
- CENTRAL_EXCHANGE_RATES
- CHATSPOT
- CLONE_OBJECTS
- COMMUNICATOR
- COMPANIES
- COMPANY_FAMILIES
- COMPANY_INSIGHTS
- CONNECTED_ACCOUNT
- CONTACTS
- CONTACTS_WEB
- CONTENT_MEMBERSHIP
- CONVERSATIONAL_ENRICHMENT
- CONVERSATIONS
- CRM_PROCESSES_PLATFORM
- CRM_UI
- CRM_UI_BULK_ACTION
- CUSTOMER_AGENT
- CUSTOMER_PORTAL
- DATA_ENRICHMENT
- DATA_QUALITY
- DATASET
- DEALS
- DEFAULT
- DELETE_OBJECTS
- DI_WRITE_TO_CRM
- EMAIL
- EMAIL_INBOX_IMPORT
- EMAIL_INTEGRATION
- ENGAGEMENTS
- EXTENSION
- FILE_MANAGER
- FLYWHEEL_PRODUCT_DATA_SYNC
- FORECASTING
- FORM
- FORWARD_TO_CRM
- GMAIL_INTEGRATION
- GOALS
- HEISENBERG
- HELP_DESK
- HELP_DESK_AI
- IMPORT
- INTEGRATION
- INTEGRATIONS_PLATFORM
- INTEGRATIONS_SYNC
- INTENT
- INTERNAL_PROCESSING
- LEADIN
- LEGAL_BASIS_REMEDIATION
- MARKET_SOURCING
- MARKETPLACE
- MARKETS
- MEETINGS
- MERGE_COMPANIES
- MERGE_CONTACTS
- MERGE_OBJECTS
- MERGE_REVERT_OBJECTS
- MICROAPPS
- MIGRATION
- MOBILE_ANDROID
- MOBILE_IOS
- PAYMENTS
- PIPELINE_SETTINGS
- PLAYBOOKS
- PORTAL_OBJECT_SYNC
- PORTAL_USER_ASSOCIATOR
- PRESENTATIONS
- PRIMARY_AUTOMATION
- PROPERTY_DEFAULT_VALUE
- PROPERTY_RESTORE
- PROPERTY_SETTINGS
- PROSPECTING_AGENT
- QUOTAS
- QUOTES
- RECYCLING_BIN
- RESTORE_OBJECTS
- REVENUE_PLATFORM
- SALES
- SALES_MESSAGES
- SALESFORCE
- SEQUENCES
- SETTINGS
- SIDEKICK
- SIGNALS
- SLACK_INTEGRATION
- SMART_DATA_CAPTURE
- SOCIAL
- SUCCESS
- TALLY
- TASK
- UNKNOWN
- WAL_INCREMENTAL
- WORK_UI
- WORKFLOW_CONTACT_DELETE_ACTION
- WORKFLOWS
hs_engagement_source_id:
type: string
description: >-
The ID associated with the process created the engagement. Should
always be empty when creating meeting events through this API.
hs_include_description_in_reminder:
type: string
description: Whether to include the meeting description in the reminder.
hs_internal_meeting_notes:
type: string
description: Internal notes related to the meeting.
hs_meeting_body:
type: string
description: The description of the meeting and calendar event.
hs_meeting_end_time:
type: string
description: The end time of the meeting in ISO 8601 format.
format: date-time
hs_meeting_external_url:
type: string
description: The calendar event URL for the meeting.
hs_meeting_location:
type: string
description: >-
The physical address, virtual location, or phone number where the
meeting will take place.
hs_meeting_location_type:
type: string
description: >-
The type of location for the meeting. Acceptable values are:
ADDRESS, CUSTOM, PHONE.
enum:
- ADDRESS
- CUSTOM
- PHONE
hs_meeting_outcome:
type: string
description: >-
The outcome of the meeting. Acceptable default values are:
SCHEDULED, COMPLETED, RESCHEDULED, NO_SHOW, CANCELED. This property
can be changed to include additional custom values.
hs_meeting_start_time:
type: string
description: The start time of the meeting in ISO 8601 format.
format: date-time
hs_meeting_title:
type: string
description: The title of the meeting and calendar event.
hs_timestamp:
type: string
description: >-
The time that the meeting should start in ISO 8601 format. This
value should be the same as `hs_meeting_start_time`.
format: date-time
hs_unique_id:
type: string
description: The unique ID of the created calendar event.
hubspot_owner_id:
type: string
description: The owner ID of the HubSpot user hosting the meeting.
Error:
required:
- category
- correlationId
- message
type: object
properties:
category:
type: string
description: The error category
context:
type: object
additionalProperties:
type: array
items:
type: string
description: Context about the error condition
example: >-
{invalidPropertyName=[propertyValue], missingScopes=[scope1,
scope2]}
correlationId:
type: string
description: >-
A unique identifier for the request. Include this value with any
error reports or support tickets
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: further information about the error
items:
$ref: '#/components/schemas/ErrorDetail'
links:
type: object
additionalProperties:
type: string
description: >-
A map of link names to associated URIs containing documentation
about the error or recommended remediation steps
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate
example: An error occurred
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error
example:
message: Invalid input (details will vary based on the error)
correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
category: VALIDATION_ERROR
links:
knowledge-base: https://www.hubspot.com/products/service/knowledge-base
PublicObjectId:
required:
- id
type: object
properties:
id:
type: string
description: The unique identifier for an object.
description: Contains the Id of a Public Object
AssociationSpec:
required:
- associationCategory
- associationTypeId
type: object
properties:
associationCategory:
type: string
description: The category of the association, such as "HUBSPOT_DEFINED".
enum:
- HUBSPOT_DEFINED
- INTEGRATOR_DEFINED
- USER_DEFINED
- WORK
associationTypeId:
type: integer
description: The ID representing the specific type of association.
format: int32
description: >-
Defines the type, direction, and details of the relationship between two
CRM objects.
ExternalReminder:
required:
- numberOfTimeUnits
- timeUnit
type: object
properties:
numberOfTimeUnits:
type: integer
description: >-
The number of timeUnits prior to the meeting start when the reminder
will be sent.
format: int32
timeUnit:
type: string
description: 'Accepted values are: WEEKS, DAYS, HOURS, MINUTES.'
enum:
- DAYS
- HOURS
- MINUTES
- WEEKS
ErrorDetail:
required:
- message
type: object
properties:
code:
type: string
description: The status code associated with the error detail
context:
type: object
additionalProperties:
type: array
items:
type: string
description: Context about the error condition
example: '{missingScopes=[scope1, scope2]}'
in:
type: string
description: The name of the field or parameter in which the error was found.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error
responses:
Error:
description: An error occurred.
content:
'*/*':
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.hubspot.com/oauth/authorize
tokenUrl: https://api.hubapi.com/oauth/v1/token
scopes:
crm.objects.contacts.sensitive.write.v2: ''
meetings-write: ''
scheduler.meetings.meeting-link.read: ''
````
{product.name} -
{product.level}
)}