---
title: "Create event"
method: POST
path: "/v1/links/{link_id}/events"
tags: ["Events"]
---

# Create event

`POST /v1/links/{link_id}/events`

## Request

- Base URL: `https://api.savvycal.com`
- URL: `https://api.savvycal.com/v1/links/{link_id}/events`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/oauth/authorize`
    - Token URL: `/oauth/token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/savvycal/apis/savvycal-meetings-api/docs/v1/links/:link_id/events/post.ts> (a function with typed inputs; its response is checked against the schema)

**Note about time slots:** You'll only be able to create events that match an available time slot for the underlying scheduling link. You can use the [Get available time slots](/developers/v1/api/get-link-slots) endpoint to query for time slots.

**Note about conferencing:** For some conferencing providers (like Zoom), the meeting information is not guaranteed to appear in the response body. If our initial attempt to create the meeting room fails, we will retry and attach the information to event later.

## Path parameters

- `link_id` string, required

## Request body

- CreateEventRequest
  - `display_name` string, required: The scheduler's full name.
  - `email` string, email, required: The scheduler's email address.
  - `end_at` string, date-time, required
  - `fields` object[]: The scheduler's answers to the scheduling link's custom fields. Get the fields from the [Get a scheduling link](/developers/v1/api/get-scheduling-link) endpoint. Answer `short_text`, `long_text`, `url`, and `hidden` fields with `value`. Answer `checkboxes`, `radios`, and `select` fields with `options`, picked from the field's `options`. To select one option, you can instead put that option's exact text in `value`.
    - `id` string, required: The field ID, as returned by the scheduling link.
    - `label` string, required
    - `options` FieldOption[]: The selected options for a `checkboxes`, `radios`, or `select` field. Pass one option for `radios` and `select`.
      - `id` string, required
      - `value` string, required
    - `type` 'short_text' | 'long_text' | 'checkboxes' | 'radios' | 'select' | 'url' | 'hidden', required
    - `value` string, nullable: The answer for a `short_text`, `long_text`, `url`, or `hidden` field. For a `checkboxes`, `radios`, or `select` field sent without `options`, the exact text of the one option to select.
  - `metadata` object
  - `phone_number` string, nullable: The scheduler's phone number, formatted like `+15555555555` (optional unless "Always gather phone number" is enabled in the scheduling link settings).
  - `start_at` string, date-time, required
  - `time_zone` string, required: The scheduler's local Olson time zone.

## Response `200`

Success

- SingleEventResponse
  - `canceled_at` string, date-time, nullable
  - `rescheduled_at` string, date-time, nullable
  - `location_settings` object[]: Each entry has a `type` and that type's settings.
    - `type` string, required
  - `description_settings` object, required: Which details the calendar event description includes
    - `include_attendees` boolean, required
    - `include_fields` boolean, required
    - `include_link_name` boolean, required
  - `location` string, nullable: The location on the calendar event: the event's location, or else the conferencing join URL or instructions.
  - `buffer_before` integer, required: Buffer before the event, in minutes
  - `additional_info` string, nullable
  - `duration` integer, required: Duration in minutes
  - `uuid` string, uuid, required
  - `reschedule_reason` string, nullable
  - `conferencing` object, required
    - `instructions` string, nullable
    - `join_url` string, nullable
    - `meeting_id` string, nullable
    - `type` string, required
  - `link` LinkPreview
    - `description` string, required: Link description, as HTML. Empty when the link has no description.
    - `id` string, required
    - `name` string, required
    - `private_name` string, nullable, required: Private link name. `null` when the current user can't edit the link or the link has no private name.
    - `slug` string, required
  - `poll` PollPreview
    - `id` string, required
    - `name` string, required
    - `slug` string, required
  - `summary` string, required: Event title
  - `original_end_at` string, date-time, nullable: Original end time (if rescheduled)
  - `description` string: The scheduling link's description at the time of booking, as HTML. Empty when there is no description.
  - `id` string, required
  - `cancel_reason` string, nullable
  - `organizer` EventAttendee, required
    - `display_name` string, required
    - `email` string, required
    - `fields` EventField[], required: The attendee's answers to the scheduling link's custom fields
      - `id` string, required
      - `label` string, required
      - `options` FieldOption[], required: The selected options for a `checkboxes`, `radios`, or `select` field. Empty for other field types.
        - `id` string, required
        - `value` string, required
      - `type` 'short_text' | 'long_text' | 'checkboxes' | 'radios' | 'select' | 'url' | 'hidden', required
      - `value` string, nullable, required: The answer as text. For a `checkboxes` field, the selected option values joined by newlines. `null` when the field has no answer.
    - `first_name` string, required: The first word of `display_name`
    - `id` string, required
    - `is_organizer` boolean, required
    - `last_name` string, required: The rest of `display_name`. Empty when `display_name` is one word.
    - `marketing_opt_in` boolean, required
    - `phone_number` string, nullable
    - `response_status` 'accepted' | 'tentative' | 'needs_action' | 'declined', required
    - `time_zone` string, required
  - `is_group_session` boolean, nullable, required: Whether this is a group session. `null` on some older events.
  - `original_start_at` string, date-time, nullable: Original start time (if rescheduled)
  - `start_at` string, date-time, required
  - `url` string, uri, required: Public URL for the event
  - `payment` Payment
    - `amount_total` integer, nullable, required: Total amount charged (in cents)
    - `state` 'awaiting_checkout' | 'paid', required
    - `url` string, uri, nullable, required: A link to the Stripe dashboard page for the payment (only available after checkout is completed)
  - `maximum_group_size` integer, nullable, required: Maximum number of attendees for group session. `null` for events booked from a poll.
  - `end_at` string, date-time, required
  - `state` 'confirmed' | 'canceled' | 'awaiting_reschedule' | 'awaiting_checkout' | 'checkout_expired' | 'awaiting_approval' | 'declined' | 'tentative', required
  - `attendees` EventAttendee[], required
    - `display_name` string, required
    - `email` string, required
    - `fields` EventField[], required: The attendee's answers to the scheduling link's custom fields
      - `id` string, required
      - `label` string, required
      - `options` FieldOption[], required: The selected options for a `checkboxes`, `radios`, or `select` field. Empty for other field types.
        - `id` string, required
        - `value` string, required
      - `type` 'short_text' | 'long_text' | 'checkboxes' | 'radios' | 'select' | 'url' | 'hidden', required
      - `value` string, nullable, required: The answer as text. For a `checkboxes` field, the selected option values joined by newlines. `null` when the field has no answer.
    - `first_name` string, required: The first word of `display_name`
    - `id` string, required
    - `is_organizer` boolean, required
    - `last_name` string, required: The rest of `display_name`. Empty when `display_name` is one word.
    - `marketing_opt_in` boolean, required
    - `phone_number` string, nullable
    - `response_status` 'accepted' | 'tentative' | 'needs_action' | 'declined', required
    - `time_zone` string, required
  - `scheduler` EventAttendee
    - `display_name` string, required
    - `email` string, required
    - `fields` EventField[], required: The attendee's answers to the scheduling link's custom fields
      - `id` string, required
      - `label` string, required
      - `options` FieldOption[], required: The selected options for a `checkboxes`, `radios`, or `select` field. Empty for other field types.
        - `id` string, required
        - `value` string, required
      - `type` 'short_text' | 'long_text' | 'checkboxes' | 'radios' | 'select' | 'url' | 'hidden', required
      - `value` string, nullable, required: The answer as text. For a `checkboxes` field, the selected option values joined by newlines. `null` when the field has no answer.
    - `first_name` string, required: The first word of `display_name`
    - `id` string, required
    - `is_organizer` boolean, required
    - `last_name` string, required: The rest of `display_name`. Empty when `display_name` is one word.
    - `marketing_opt_in` boolean, required
    - `phone_number` string, nullable
    - `response_status` 'accepted' | 'tentative' | 'needs_action' | 'declined', required
    - `time_zone` string, required
  - `scope` ScopePreview: Preview of a scope/team
    - `id` string, required
    - `name` string, required
    - `slug` string, required
  - `buffer_after` integer, required: Buffer after the event, in minutes
  - `metadata` object, required: The custom `metadata` sent when the event was created.
  - `created_at` string, date-time, required

## Other responses

- `401`: Unauthorized
- `404`: Not Found
- `422`: Validation errors
- `429`: More than 10 requests to create an event on the link in a minute, including failed ones

---

[API](https://skmtc.dev/savvycal/apis/savvycal-meetings-api.md) - [All operations](https://skmtc.dev/savvycal/apis/savvycal-meetings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/savvycal/apis/savvycal-meetings-api/revisions/398985d699a3?raw)