> ## 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 meeting event in your HubSpot account. This endpoint allows you to specify details such as the meeting title, start and end times, and associated users. The organizerUserId is required to identify the meeting organizer.
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 meeting
description: >-
Create a new calendar meeting event in your HubSpot account. This
endpoint allows you to specify details such as the meeting title, start
and end times, and associated users. The organizerUserId is required to
identify the meeting organizer.
operationId: post-/scheduler/2026-03/meetings/calendar
parameters:
- name: organizerUserId
in: query
description: >-
The unique identifier of the user organizing the meeting. This
parameter is required.
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.services.write
- oauth2:
- crm.objects.projects.sensitive.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:
- crm.schemas.meetings.write
components:
schemas:
ExternalCalendarMeetingEventCreateRequest:
required:
- associations
- emailReminderSchedule
- properties
- timezone
type: object
properties:
associations:
type: array
description: >-
An array of associations related to the meeting event, each
represented by an ExternalAssociationCreateRequest object.
items:
$ref: '#/components/schemas/ExternalAssociationCreateRequest'
emailReminderSchedule:
$ref: '#/components/schemas/ExternalEmailReminderSchedule'
properties:
$ref: '#/components/schemas/ExternalCalendarMeetingEventCreateProperties'
timezone:
type: string
description: >-
A string representing the timezone in which the meeting event is
scheduled.
ExternalCalenderMeetingEventResponse:
required:
- createdAt
- id
- lastUpdatedAt
- properties
type: object
properties:
createdAt:
type: string
description: >-
The date and time when the calendar meeting event was created, in
ISO 8601 format.
format: date-time
id:
type: string
description: The unique identifier for the calendar meeting event.
lastUpdatedAt:
type: string
description: >-
The date and time when the calendar 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
description: >-
An array of association specifications, detailing the types of
associations to be created. Each item in the array is an object that
defines the association type.
items:
$ref: '#/components/schemas/AssociationSpec'
ExternalEmailReminderSchedule:
required:
- reminders
- shouldIncludeInviteDescription
type: object
properties:
reminders:
type: array
description: >-
An array of ExternalReminder objects that specify the timing and
frequency of the email reminders.
items:
$ref: '#/components/schemas/ExternalReminder'
shouldIncludeInviteDescription:
type: boolean
description: >-
A boolean indicating whether the invite description should be
included in the email 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 type of activity for the meeting. This is a string value.
hs_attachment_ids:
type: array
description: >-
An array of strings representing the IDs of attachments associated
with the meeting.
items:
type: string
hs_attendee_owner_ids:
type: array
description: >-
An array of strings representing the IDs of the owners of the
attendees for the meeting.
items:
type: string
hs_internal_meeting_notes:
type: string
description: Internal notes for the meeting. This is a string value.
hs_meeting_body:
type: string
description: >-
The body content or description of the meeting. This is a string
value.
hs_meeting_end_time:
type: string
description: The end time of the meeting, in ISO 8601 format.
format: date-time
hs_meeting_location:
type: string
description: The location of the meeting. This is a string value.
hs_meeting_location_type:
type: string
description: >-
The type of location for the meeting. Valid values include 'PHONE',
'ADDRESS', and 'CUSTOM'.
enum:
- ADDRESS
- CUSTOM
- PHONE
hs_meeting_outcome:
type: string
description: A string representing the outcome of the meeting.
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. This is a string value.
hs_timestamp:
type: string
description: >-
A timestamp indicating when the meeting event was created, in ISO
8601 format.
format: date-time
hubspot_owner_id:
type: string
description: >-
The unique identifier of the HubSpot owner associated with 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 type of activity associated with the meeting.
hs_attachment_ids:
type: array
description: >-
An array of unique identifiers for attachments associated with the
meeting.
items:
type: string
hs_attendee_owner_ids:
type: array
description: An array of unique identifiers for the owners of the attendees.
items:
type: string
hs_engagement_source:
type: string
description: >-
The source of the engagement. Valid values include a wide range of
sources such as 'UNKNOWN', 'IMPORT', 'API', 'FORM', and many others.
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 unique identifier for the source of the engagement.
hs_include_description_in_reminder:
type: string
description: >-
Indicates whether the meeting description should be included in
reminders.
hs_internal_meeting_notes:
type: string
description: Internal notes related to the meeting.
hs_meeting_body:
type: string
description: The body or description of the meeting.
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 external URL associated with the meeting.
hs_meeting_location:
type: string
description: The location where the meeting is held.
hs_meeting_location_type:
type: string
description: >-
The type of location for the meeting. Valid values include 'PHONE',
'ADDRESS', and 'CUSTOM'.
enum:
- ADDRESS
- CUSTOM
- PHONE
hs_meeting_outcome:
type: string
description: The outcome of the meeting.
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.
hs_timestamp:
type: string
description: >-
A timestamp indicating when the meeting event was recorded, in ISO
8601 format.
format: date-time
hs_unique_id:
type: string
description: A unique identifier for the meeting event.
hubspot_owner_id:
type: string
description: >-
The unique identifier of the HubSpot owner associated with the
meeting.
Error:
required:
- category
- correlationId
- message
type: object
properties:
category:
type: string
description: The error category. It is a string.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition. It is an object where each
property is an array of strings.
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. It is a string in UUID format.
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: >-
Further information about the error. It is an array of ErrorDetail
objects.
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. It is an object
where each property is a string.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate. It is a string.
example: An error occurred
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error. It is a string.
description: >-
Represents an error response returned by the API when an operation
fails. This component is used in various endpoints to provide detailed
information about the error encountered.
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 the public object. It is a string that
serves as a reference to the object within the API.
description: Contains the Id of a Public Object
AssociationSpec:
required:
- associationCategory
- associationTypeId
type: object
properties:
associationCategory:
type: string
description: >-
A string indicating the category of the association. Valid values
include 'HUBSPOT_DEFINED', 'USER_DEFINED', 'INTEGRATOR_DEFINED', and
'WORK'.
enum:
- HUBSPOT_DEFINED
- INTEGRATOR_DEFINED
- USER_DEFINED
- WORK
associationTypeId:
type: integer
description: >-
An integer representing the unique identifier for the 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 time units before the meeting when the reminder should
be sent. This is an integer value.
format: int32
timeUnit:
type: string
description: >-
The unit of time for the reminder. Valid values include 'WEEKS',
'DAYS', 'HOURS', and '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, represented as an object where
each property is an array of strings providing additional
information.
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. This is a required field.
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error.
description: >-
Represents detailed information about an error that occurred in the API.
This component is used to provide additional context and specifics about
errors, typically as part of an error response.
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: ''
crm.schemas.meetings.write: ''
scheduler.meetings.meeting-link.read: ''
````
{product.name} -
{product.level}
)}