> Calendly developer docs. For page Markdown, append .md to any URL. > Index: https://developer.calendly.com/llms.txt > API catalog: https://developer.calendly.com/.well-known/api-catalog > OpenAPI: https://developer.calendly.com/openapi/calendly-api.yaml > OAuth authorization server: https://calendly.com/.well-known/oauth-authorization-server > MCP protected resource: https://mcp.calendly.com/.well-known/oauth-protected-resource > Scheduling MCP endpoint: https://mcp.calendly.com > Docs search MCP: https://developer.calendly.com/_mcp/server # Create Event Invitee (Scheduling API) POST https://api.calendly.com/invitees Content-Type: application/json Creates a new booking for an event invitee. Use this endpoint to book an invitee directly from your app without redirects, iframes, or Calendly-hosted UI. Standard notifications, calendar invites, reschedules, and workflows run as if booked via the Calendly UI. **NOTE:** * Access to this endpoint is limited to Calendly users on paid plans (Standard and above). Users on the Free plan will receive a 403 Forbidden response. > `scheduled_events:write` Reference: https://developer.calendly.com/api-docs/calendly-api/scheduled-events/create-event-invitee ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 - `Authorization` header (bearer token, required) — Personal Access Token ## Request ### Body (application/json) This endpoint expects an object. - `event_type` (string, required) — Canonical reference (unique identifier) for the event type being scheduled - `start_time` (string, required) — The start time in UTC of the scheduled event - `invitee` (InviteesPostRequestBodyContentApplicationJsonSchemaInvitee, required) - `location` (InviteeLocation, optional) — The polymorphic base type for an event location that Calendly supports. Note: - Location.kind must be supplied if location is defined. - Location must match location specified on the EventType. - Do not pass the location object for an EventType with a round_robin pooling_type. - `questions_and_answers` (list of InviteeQuestionAndAnswer, optional) - `tracking` (InviteeTracking, optional) — The UTM and Salesforce tracking parameters associated with an Invitee - `event_guests` (list of string, optional) — Emails of invitee guests. Max 10. ## Response ### 201 Created - `resource` (Invitee, required) — An individual who has been invited to meet with a Calendly member ## Errors ### 400 Bad Request Error Request is not valid - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 401 Unauthorized Error Cannot authenticate caller - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 403 Forbidden Error Caller not authorized to perform this action or insufficient scope - `Post-inviteeRequestForbiddenError` ### 404 Not Found Error Requested resource not found - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 500 Internal Server Error An error has occurred on the server - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ## Types ### InviteesPostRequestBodyContentApplicationJsonSchemaInvitee - `email` (string, required) — The email of the invitee - `timezone` (string, required) — The timezone of the invitee - `name` (string, optional) — The full name of the invitee. **Required if** `first_name` **is not provided** - `first_name` (string, optional) — The first name of the invitee. **Required if** `name` **is not provided** - `last_name` (string, optional) — The last name of the invitee - `text_reminder_number` (string, optional) — Invitee's phone number for SMS reminders. Must be a valid phone number (e.g. +14155551234) ### InviteeLocation The polymorphic base type for an event location that Calendly supports. Note: - Location.kind must be supplied if location is defined. - Location must match location specified on the EventType. - Do not pass the location object for an EventType with a round_robin pooling_type. ### InviteeQuestionAndAnswer A response to a question on a booking page form. Required questions must be included in the body and match on the question string exactly. - `question` (string, required) — A question for the invitee. String is case sensitive and must exactly match the question. - `answer` (string, required) — The invitee's response to the question - `position` (integer, required) — The position of the question in relation to others ### InviteeTracking The UTM and Salesforce tracking parameters associated with an Invitee - `utm_campaign` (string, required, nullable) — The UTM parameter used to track a campaign - `utm_source` (string, required, nullable) — The UTM parameter that identifies the source (platform where the traffic originates) - `utm_medium` (string, required, nullable) — The UTM parameter that identifies the type of input (e.g. Cost Per Click (CPC), social media, affiliate or QR code) - `utm_content` (string, required, nullable) — UTM content tracking parameter - `utm_term` (string, required, nullable) — The UTM parameter used to track keywords - `salesforce_uuid` (string, required, nullable) — The Salesforce record unique identifier ### Invitee An individual who has been invited to meet with a Calendly member - `uri` (string, required) — Canonical reference (unique identifier) for the invitee - `email` (string, required) — The invitee’s email address - `first_name` (string, required, nullable) — The first name of the invitee who booked the event when the event type is configured to use separate fields for first name and last name. Null when event type is configured to use a single field for name. - `last_name` (string, required, nullable) — The last name of the invitee who booked the event when the event type is configured to use separate fields for first name and last name. Null when event type is configured to use a single field for name. - `name` (string, required) — The invitee’s name (in human-readable format) - `status` (enum, required) — Indicates if the invitee is "active" or "canceled" - Allowed values: `active`, `canceled` - `questions_and_answers` (list of InviteeQuestionAndAnswer, required) — A collection of the invitee's responses to questions on the event booking confirmation form - `timezone` (string, required, nullable) — Time zone to use when displaying time to the invitee - `event` (string, required) — A reference to the event - `created_at` (string, required) — The moment when the event was created (e.g. "2020-01-02T03:04:05.678123Z") - `updated_at` (string, required) — The moment when the event was last updated (e.g. "2020-01-02T03:04:05.678123Z") - `tracking` (InviteeTracking, required) — The UTM and Salesforce tracking parameters associated with an Invitee - `text_reminder_number` (string, required, nullable) — The phone number to use when sending text (SMS) reminders - `rescheduled` (boolean, required) — Indicates if this invitee has rescheduled. If `true`, a reference to the new Invitee instance is provided in the `new_invitee` field. - `old_invitee` (string, required, nullable) — Reference to old Invitee instance that got rescheduled - `new_invitee` (string, required, nullable) — Link to new invitee, after reschedule - `cancel_url` (string, required) — Link to cancelling the event for the invitee - `reschedule_url` (string, required) — Link to rescheduling the event for the invitee - `routing_form_submission` (string, required, nullable) — Reference to a routing form submission that redirected the invitee to a booking page. - `payment` (InviteePayment, required, nullable) — Invitee payment - `no_show` (InviteeAssociatedNoShow, required, nullable) — Provides data pertaining to the associated no show for the Invitee - `reconfirmation` (InviteeReconfirmation, required, nullable) — Assuming reconfirmation is enabled for the event type, when reconfirmation is requested this object is present with a `created_at` that reflects when the reconfirmation notification was sent. Once the invitee has reconfirmed the `confirmed_at` attribute will change from `null` to a timestamp that reflects when they took action. - `scheduling_method` (enum, required, nullable) — The method used to schedule the event - Allowed values: `instant_book`, `api` - `invitee_scheduled_by` (string, required, nullable) — Reference to user URI who scheduled the event - `cancellation` (Cancellation, optional) — Provides data pertaining to the cancellation of the Event or the Invitee ### ErrorResponseDetailsItem - `message` (string, required) - `parameter` (string, optional) - `code` (string, optional) ### InviteesError Caller not authorized to perform this action - `details` (list of ErrorResponseDetailsItem, optional) - `message` (enum, optional) - Allowed values: `You do not have permission to access this resource.`, `You do not have permission`, `The Scheduling API is only available on paid Calendly plans. Upgrade your plan to access this feature.` - `title` (enum, optional) - Allowed values: `Permission Denied` ### InsufficientScopeError Caller does not have required oauth scopes - `title` (enum, required) - Allowed values: `Insufficient scope` - `message` (enum, required) - Allowed values: `This operation requires the scopes listed in the 'required_scopes' array.` - `required_scopes` (list of string, required) ### InviteeInPersonMeeting Information for an In Person Meeting - `kind` (enum, required) — Indicates that the event will be an in-person meeting. - Allowed values: `physical` - `location` (string, required) — The specific physical location ### InviteeInboundCall Information for an Inbound Call - `kind` (enum, required) — Indicates that the invitee will call the event host - Allowed values: `inbound_call` ### InviteeOutboundCall Information about an Outbound Call - `kind` (enum, required) — Indicates that the event host (publisher) will call the invitee - Allowed values: `outbound_call` - `location` (string, required) — The phone number the event host (publisher) will use to call the invitee ### InviteeZoomConference Information about a Zoom Conference - `kind` (enum, required) — The event location is a Zoom conference - Allowed values: `zoom_conference` ### InviteeGoogleConference Information for a Google Conference - `kind` (enum, required) — The event location is a Google Meet or Hangouts conference - Allowed values: `google_conference` ### InviteeGotoMeetingConference Information for a GotoMeeting Conference - `kind` (enum, required) — The event location is a GoToMeeting conference - Allowed values: `gotomeeting_conference` ### InviteeMicrosoftTeamsConference Information for a Microsoft Teams Conference - `kind` (enum, required) — The event location is a Microsoft Teams conference - Allowed values: `microsoft_teams_conference` ### InviteeWebExConference Information about a WebEx Conference - `kind` (enum, required) — The event location is a WebEx conference - Allowed values: `webex_conference` ### InviteeInviteeSpecifiedLocation Information for an Invitee Specified Location - `kind` (enum, required) — Indicates that the event location will be selected by the invitee - Allowed values: `ask_invitee` - `location` (string, required) — The event location description provided by the invitee ### InviteeCustomLocation Information for a Custom Location - `kind` (enum, required) — The event location doesn't fall into a standard category defined by the event host (publisher) - Allowed values: `custom` - `location` (string, required) — The specific custom location ### InviteePayment Invitee payment - `external_id` (string, required) — Unique identifier for the payment - `provider` (enum, required) — Payment provider - Allowed values: `stripe`, `paypal` - `amount` (float, required) — The amount of the payment - `currency` (enum, required) — The currency format that the payment is in. - Allowed values: `AUD`, `CAD`, `EUR`, `GBP`, `USD` - `terms` (string, required, nullable) — Terms of the payment - `successful` (boolean, required) — Indicates whether the payment was successfully processed ### InviteeAssociatedNoShow Provides data pertaining to the associated no show for the Invitee - `uri` (string, required) — Canonical reference (unique identifier) for the no show - `created_at` (string, required) — The moment when the no show was created ### InviteeReconfirmation Assuming reconfirmation is enabled for the event type, when reconfirmation is requested this object is present with a `created_at` that reflects when the reconfirmation notification was sent. Once the invitee has reconfirmed the `confirmed_at` attribute will change from `null` to a timestamp that reflects when they took action. - `created_at` (string, required) — When the reconfirmation was created. - `confirmed_at` (string, required, nullable) — When the Invitee confirmed their attendance. ### Cancellation Provides data pertaining to the cancellation of the Event or the Invitee - `canceled_by` (string, required) — Name of the person whom canceled - `reason` (string, required, nullable) — Reason that the cancellation occurred - `canceler_type` (enum, required) - Allowed values: `host`, `invitee` - `created_at` (string, required) — The moment when the cancellation was created ## Examples **Request** ```json { "event_type": "https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA", "start_time": "2019-08-07T06:05:04.321123Z", "invitee": { "email": "test@example.com", "timezone": "America/New_York" } } ``` **Response** ```json { "resource": { "uri": "https://api.calendly.com/scheduled_events/AAAAAAAAAAAAAAAA/invitees/AAAAAAAAAAAAAAAA", "email": "test@example.com", "first_name": "John", "last_name": "Doe", "name": "John Doe", "status": "active", "questions_and_answers": [], "timezone": "America/New_York", "event": "https://api.calendly.com/scheduled_events/AAAAAAAAAAAAAAAA", "created_at": "2020-11-23T17:51:18.327602Z", "updated_at": "2020-11-23T17:51:18.341657Z", "tracking": { "utm_campaign": null, "utm_source": null, "utm_medium": null, "utm_content": null, "utm_term": null, "salesforce_uuid": null }, "text_reminder_number": null, "rescheduled": false, "old_invitee": null, "new_invitee": null, "cancel_url": "https://calendly.com/cancellations/AAAAAAAAAAAAAAAA", "reschedule_url": "https://calendly.com/reschedulings/AAAAAAAAAAAAAAAA", "routing_form_submission": "https://api.calendly.com/routing_form_submissions/AAAAAAAAAAAAAAAA", "payment": { "external_id": "ch_AAAAAAAAAAAAAAAA", "provider": "stripe", "amount": 1234.56, "currency": "USD", "terms": "sample terms of payment (up to 1,024 characters)", "successful": true }, "no_show": { "uri": "https://api.calendly.com/invitee_no_shows/AAAAAAAAAAAAAAAA", "created_at": "2020-11-23T17:51:18.341657Z" }, "reconfirmation": { "created_at": "2020-11-23T17:51:18.341657Z", "confirmed_at": "2020-11-23T20:01:18.341657Z" }, "scheduling_method": null, "invitee_scheduled_by": null } } ``` **SDK Code** ```typescript import { CalendlyClient } from "calendly"; async function main() { const client = new CalendlyClient({ token: "YOUR_TOKEN_HERE", }); await client.scheduledEvents.createEventInvitee({ eventType: "https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA", startTime: new Date("2019-08-07T06:05:04.321123Z"), invitee: { email: "test@example.com", timezone: "America/New_York", }, }); } main(); ``` ```python import requests url = "https://api.calendly.com/invitees" payload = { "event_type": "https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA", "start_time": "2019-08-07T06:05:04.321123Z", "invitee": { "email": "test@example.com", "timezone": "America/New_York" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.calendly.com/invitees" payload := strings.NewReader("{\n \"event_type\": \"https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA\",\n \"start_time\": \"2019-08-07T06:05:04.321123Z\",\n \"invitee\": {\n \"email\": \"test@example.com\",\n \"timezone\": \"America/New_York\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.calendly.com/invitees") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"event_type\": \"https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA\",\n \"start_time\": \"2019-08-07T06:05:04.321123Z\",\n \"invitee\": {\n \"email\": \"test@example.com\",\n \"timezone\": \"America/New_York\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.calendly.com/invitees") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"event_type\": \"https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA\",\n \"start_time\": \"2019-08-07T06:05:04.321123Z\",\n \"invitee\": {\n \"email\": \"test@example.com\",\n \"timezone\": \"America/New_York\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.calendly.com/invitees', [ 'body' => '{ "event_type": "https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA", "start_time": "2019-08-07T06:05:04.321123Z", "invitee": { "email": "test@example.com", "timezone": "America/New_York" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.calendly.com/invitees"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"event_type\": \"https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA\",\n \"start_time\": \"2019-08-07T06:05:04.321123Z\",\n \"invitee\": {\n \"email\": \"test@example.com\",\n \"timezone\": \"America/New_York\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "event_type": "https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA", "start_time": "2019-08-07T06:05:04.321123Z", "invitee": [ "email": "test@example.com", "timezone": "America/New_York" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/invitees")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```