{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/nylas/main/json-schema/nylas-event-create-schema.json",
  "title": "create_event",
  "x-generated": "2026-10-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nylas-events-api-openapi.yml#/components/schemas/event_create",
  "type": "object",
  "required": [
    "when"
  ],
  "properties": {
    "busy": {
      "$ref": "#/$defs/event_busy"
    },
    "capacity": {
      "$ref": "#/$defs/event_capacity"
    },
    "conferencing": {
      "$ref": "#/$defs/event_conferencing_request"
    },
    "description": {
      "$ref": "#/$defs/event_description"
    },
    "hide_participants": {
      "$ref": "#/$defs/event_hide_participants"
    },
    "location": {
      "$ref": "#/$defs/event_location"
    },
    "metadata": {
      "$ref": "#/$defs/metadata"
    },
    "notetaker": {
      "$ref": "#/$defs/event_sync"
    },
    "participants": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/event_participants_create_update"
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/event_resources"
      }
    },
    "recurrence": {
      "$ref": "#/$defs/event_recurrence"
    },
    "reminders": {
      "$ref": "#/$defs/event_reminders_create"
    },
    "title": {
      "$ref": "#/$defs/event_title"
    },
    "visibility": {
      "$ref": "#/$defs/event_visibility"
    },
    "when": {
      "$ref": "#/$defs/event_when"
    }
  },
  "$defs": {
    "event_busy": {
      "title": "Event busy settings",
      "type": [
        "boolean",
        "null"
      ],
      "description": "When `true`, shows the event's time block as \"busy\" on shared or public calendars. This might be\ncalled \"transparency\" in some systems. This field may be `null` if not explicitly set. Treat `null`\nthe same as `true` (the default behavior)."
    },
    "event_capacity": {
      "title": "Event capacity settings",
      "type": "integer",
      "description": "The maximum number of participants that can attend the event."
    },
    "event_conferencing_request": {
      "title": "Event with conferencing",
      "type": "object",
      "description": "An object that lets you automatically create a conference, or enter conferencing details manually.\n\nYou can't use `autocreate` and `details` in the same request. If you do, Nylas returns an error.\n\nNylas stores conference information in the event description. To remove conference details, set\n`conferencing` to `{}` and remove the corresponding conference information from the description in\nthe same request.",
      "oneOf": [
        {
          "title": "Auto-conferencing",
          "type": "object",
          "description": "Let Nylas autocreate the conference link.",
          "properties": {
            "provider": {
              "type": "string",
              "description": "The conferencing provider that Nylas uses to create the conference.",
              "enum": [
                "Google Meet",
                "Zoom Meeting",
                "Microsoft Teams"
              ]
            },
            "autocreate": {
              "type": "object",
              "description": "When you include `autocreate` in your request, Nylas automatically creates the conference\nfor the event and appends the conferencing details to the event description.\n\nIf the `provider` is `Zoom Meeting`, your Zoom OAuth app must include the following\n[granular scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-granular/)\nfor Nylas to manage meetings on behalf of the user:\n\n- `meeting:write:meeting` — required to **create** Zoom meetings.\n- `meeting:update:meeting` — required to **update** Zoom meetings (for example, when event time or title changes).\n- `meeting:delete:meeting` — required to **delete** Zoom meetings (when events are removed).\n\nIf any of these scopes are missing, the Zoom API rejects the request. After adding scopes\nto your Zoom app, affected users must re-authenticate their grant so their access tokens\ninclude the new scopes.",
              "properties": {
                "conf_grant_id": {
                  "type": "string",
                  "description": "The grant ID of the account that hosts the conference. The user that belongs to this\ngrant acts as the conference host: they join the conference at the scheduled time and\nadmit other participants during the meeting.\n\nInclude `conf_grant_id` when the conferencing `provider` isn't available on the user's\nown account — for example, when the `provider` is `Google Meet` but the user\nauthenticated with a Microsoft account (cross-provider autocreation). When the\n`provider` is `Zoom Meeting`, `conf_grant_id` is always required."
                },
                "conf_settings": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Optional provider-specific settings that Nylas passes through when it creates the\nconference. For `Zoom Meeting`, each key is sent as a top-level parameter to\n[Zoom's Create a Meeting API](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#operation/meetingCreate)\n— for example, `agenda`, `password`, or Zoom's own `settings` object. Nylas does _not_\nvalidate these values. They can make your Zoom integration more accessible but\npotentially less secure, so review your organization's security requirements."
                }
              }
            }
          }
        },
        {
          "title": "Google Meet",
          "type": "object",
          "description": "Manually attach Google Meet details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "Google Meet"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains Google Meet conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the Google Meet conference."
                },
                "phone": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The phone number associated with the Google Meet conference. This array accepts only\none phone number."
                },
                "pin": {
                  "type": "string",
                  "description": "The PIN associated with the Google Meet conference, if applicable."
                }
              }
            }
          }
        },
        {
          "title": "Zoom Meeting",
          "type": "object",
          "description": "Manually attach Zoom Meeting details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "Zoom Meeting"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains Zoom conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the Zoom conference."
                },
                "meeting_code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "A unique ID associated with the Zoom conference."
                },
                "password": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The password for the Zoom conference, if applicable."
                }
              }
            }
          }
        },
        {
          "title": "Microsoft Teams",
          "type": "object",
          "description": "Manually attach Microsoft Teams details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "Microsoft Teams"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains Microsoft Teams conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the Microsoft Teams conference."
                }
              }
            }
          }
        },
        {
          "title": "Teams for Business",
          "type": "object",
          "description": "Manually attach Teams for Business details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "Teams for Business"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains Microsoft Teams for Enterprise conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the Microsoft Teams for Enterprise conference."
                }
              }
            }
          }
        },
        {
          "title": "Skype for Consumer",
          "type": "object",
          "description": "Manually attach Skype for Consumer details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "Skype for Consumer"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains Skype for Consumer conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the Skype for Consumer conference."
                }
              }
            }
          }
        },
        {
          "title": "Skype for Business",
          "type": "object",
          "description": "Manually attach Skype for Business details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "Skype for Business"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains Skype for Business conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the Skype for Business conference."
                }
              }
            }
          }
        },
        {
          "title": "WebEx",
          "type": "object",
          "description": "Manually attach WebEx details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "WebEx"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains WebEx conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the WebEx conference."
                },
                "password": {
                  "type": "string",
                  "description": "The password for the WebEx conference, if applicable."
                },
                "pin": {
                  "type": "string",
                  "description": "The PIN for the WebEx conference, if applicable."
                },
                "phone": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The phone number associated with the WebEx conference."
                }
              }
            }
          }
        },
        {
          "title": "GoToMeeting",
          "type": "object",
          "description": "Manually attach GoToMeeting details to the event.",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "GoToMeeting"
              ],
              "description": "The conferencing provider for the event."
            },
            "details": {
              "type": "object",
              "description": "An object that contains GoToMeeting conferencing details.",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "The URL for the GoToMeeting conference."
                },
                "meeting_code": {
                  "type": "string",
                  "description": "A unique ID associated with the GoToMeeting conference."
                },
                "password": {
                  "type": "string",
                  "description": "The password for the GoToMeeting conference, if applicable."
                },
                "phone": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The phone number associated with the GoToMeeting conference."
                }
              }
            }
          }
        }
      ]
    },
    "event_date": {
      "title": "Date",
      "type": "object",
      "description": "The date on which the event occurs, without a clock-based start\nor end time (for example, a birthday or holiday).",
      "properties": {
        "date": {
          "type": "string",
          "description": "The date of the event, in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates)."
        }
      }
    },
    "event_datespan": {
      "title": "Datespan",
      "type": "object",
      "description": "A span of days, without specific clock-based start and end times\n(for example, a business quarter or semester). For more information, see [All-day event handling](/docs/v3/calendar/using-the-events-api/#all-day-event-handling).",
      "properties": {
        "start_date": {
          "type": "string",
          "minLength": 1,
          "description": "The event's start date, in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates)."
        },
        "end_date": {
          "type": "string",
          "description": "The event's end date (inclusive), in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates)."
        }
      }
    },
    "event_description": {
      "title": "Event description",
      "type": "string",
      "description": "A brief description of the event (for example, its agenda). Nylas might return the description as\nan HTML string, depending on how the provider formats it.\n\nFor Google accounts, this field accepts a maximum of 8,192 characters."
    },
    "event_hide_participants": {
      "title": "Hide participants on event",
      "type": "boolean",
      "description": "When `true`, hides the event's list of participants."
    },
    "event_location": {
      "title": "Event location",
      "type": "string",
      "description": "The location of the event (for example, a physical address or the name of a meeting room).",
      "maxLength": 255
    },
    "event_participants_create_update": {
      "title": "Create event with these participants",
      "type": "object",
      "properties": {
        "comment": {
          "type": "string",
          "description": "A note or comment about the participant (for example, their nickname). If the participant's email address is missing, this field is also missing."
        },
        "email": {
          "type": "string",
          "description": "The participant's email address.\nFor Microsoft Graph, this field can be missing."
        },
        "name": {
          "type": "string",
          "description": "The participant's full name."
        },
        "phone_number": {
          "type": "string",
          "description": "The participant's phone number. If the participant's email address is missing, this field is also missing."
        }
      },
      "required": [
        "email"
      ]
    },
    "event_recurrence": {
      "title": "Event recurrence settings",
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of `RRULE` and `EXDATE` strings. Nylas includes this field only if the event is the main\n(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.\nYou can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.\n\nEvents inherit their timezone from the `when` object. Nylas recommends that you use the `when`\nobject to specify the event's start and end time.\n\nProvider specifics:\n- On some providers, `EXDATE` might not include exception or cancelled event timestamps. When this\nhappens, Nylas represents those event instances as separate objects in its responses.\n- Virtual calendars don't support `DTSTART` or `TZID`.\n- iCloud accounts do _not_ support changing an event from recurring to non-recurring. You can create,\nupdate, or delete information on recurring events.\n- Microsoft Graph adds one day to the `UNTIL` date."
    },
    "event_reminders_create": {
      "title": "Create reminders list",
      "type": "object",
      "description": "A list of reminders to send for the event. If left empty or omitted, the event uses the provider defaults.",
      "properties": {
        "use_default": {
          "type": "boolean",
          "title": "Use Default",
          "description": "When `true`, the event uses the calendar's default reminder settings.\n\n- **Google**: Generates a `popup`-style reminder 10 minutes before the event begins.\n- **Microsoft**: Generates a reminder 15 minutes before the event begins.\n- **iCloud**: Does not generate a reminder.\n- **EWS**: Generates a `display`-style reminder 15 minutes before the event begins."
        },
        "overrides": {
          "type": "array",
          "title": "Overrides",
          "description": "A list of reminders for the event to use when `use_default` is `false`. If this field is empty\nor omitted, and `use_default` is `false`, the event does not send reminders. If `true`, Nylas\ngenerates both the default event reminder and any reminders in the `overrides` list.\n\nYou cannot set reminder overrides if `use_default` is `true`.\n\nFor Microsoft Graph, EWS, and iCloud, you can set only one reminder per event.",
          "items": {
            "type": "object",
            "properties": {
              "reminder_minutes": {
                "type": "integer",
                "description": "The number of minutes before the event start time when a user wants to receive a reminder for this event."
              },
              "reminder_method": {
                "type": "string",
                "description": "(Google and iCloud only) The method used to notify the user about the event, with separate\noptions and default settings for each provider.\n\n- **Google**:\n  - Default: `popup`\n  - Options: `popup`, `email`\n- **iCloud**:\n  - Default: `display`\n  - Options: `display`, `sound`",
                "enum": [
                  "popup",
                  "email",
                  "display",
                  "sound"
                ]
              }
            }
          }
        }
      }
    },
    "event_resources": {
      "title": "Resource information",
      "description": "Resources are physical locations or equipment that can be reserved for events, and which are tracked using an email address with an associated calendar.",
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "description": "The resource's email address."
        },
        "name": {
          "type": "string",
          "description": "The resource's full name."
        }
      },
      "required": [
        "email"
      ]
    },
    "event_sync": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "readOnly": true,
          "description": "The Notetaker bot ID. Read-only; returned in responses but not required in create or update requests."
        },
        "meeting_settings": {
          "$ref": "#/$defs/meeting_settings"
        },
        "name": {
          "type": "string",
          "description": "The display name for the Notetaker bot.",
          "default": "Nylas Notetaker"
        }
      }
    },
    "event_time": {
      "title": "Time",
      "type": "object",
      "description": "A specific point in time (for example, the start time of an event).",
      "properties": {
        "time": {
          "type": "integer",
          "description": "The time that the meeting occurs, in seconds using the Unix timestamp format."
        },
        "timezone": {
          "type": "string",
          "description": "The timezone of the event as an\n[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string. If\npopulated, Nylas reads the value of `time` with the provided timezone."
        }
      }
    },
    "event_timespan": {
      "title": "Timespan",
      "type": "object",
      "description": "A period of time with a specified beginning and end (for example, an hour-long lunch meeting).",
      "properties": {
        "start_time": {
          "type": "integer",
          "description": "The event's start time, in seconds using the Unix timestamp format."
        },
        "end_time": {
          "type": "integer",
          "description": "The event's end time, in seconds using the Unix timestamp format."
        },
        "start_timezone": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "description": "The timezone of the event's `start_time` as an\n[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.\n\nIf you define `start_timezone` in your request, you must also define `end_timezone`."
        },
        "end_timezone": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "description": "The timezone of the event's `end_time` as an\n[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.\n\nIf you define `end_timezone` in your request, you must also define `start_timezone`."
        }
      }
    },
    "event_title": {
      "title": "Event title",
      "type": "string",
      "description": "The name of the event.",
      "maxLength": 1024
    },
    "event_visibility": {
      "title": "Event visibility on calendars",
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "default",
        "private",
        "public"
      ],
      "description": "(Not supported for iCloud events) Specifies whether the event is `public` or `private`. If not\ndefined, Nylas uses the account's default provider settings. For Google and Microsoft, event visibility is `public` by default.\n\nThe `default` enum value is only valid for Google events, where it defers to the calendar's own sharing settings. Microsoft and EWS events only support `public` and `private`; sending `default` for these providers returns a 400 error.\n\nFor virtual calendar events, you can explicitly set `visibility` to `private` or `public` on create and update requests. If not set, virtual calendar events default to `public` behavior."
    },
    "event_when": {
      "title": "When",
      "type": "object",
      "description": "An object that represents the time and duration of an event.\n\nYou can format `when` as one of four sub-objects: `time`, `timespan`, `date`, or `datespan`. These\nsub-objects allow you to capture and represent specific points in time.\n\n`time` and `timespan` objects include optional timezone support.",
      "oneOf": [
        {
          "$ref": "#/$defs/event_time"
        },
        {
          "$ref": "#/$defs/event_timespan"
        },
        {
          "$ref": "#/$defs/event_date"
        },
        {
          "$ref": "#/$defs/event_datespan"
        }
      ]
    },
    "meeting_settings": {
      "allOf": [
        {
          "$ref": "#/$defs/meeting_settings_common"
        },
        {
          "type": "object",
          "properties": {
            "transcription_settings": {
              "type": [
                "object",
                "null"
              ],
              "description": "Optional settings that tune how Notetaker transcribes audio. `transcription` must be\n`true` for these settings to take effect. Provide any combination of the fields below.\n\nThe fields fall into two independent groups:\n\n- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic\n  language detection. This declares the languages you expect; it does not translate\n  transcripts or force the recording into a specific language.\n- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward\n  domain-specific terms such as names, acronyms, and product names.\n\nSet on individual Notetakers, on calendar sync, or on event sync. When set on a calendar,\nevents inherit the value unless the event's own request overrides it. Send `null` or `{}`\nto clear inherited settings and return to default transcription behavior.\n\nSee [Set transcription languages](/docs/v3/notetaker/#set-transcription-languages) for\nsupported language codes and validation rules.",
              "properties": {
                "expected_languages": {
                  "type": "array",
                  "description": "Language codes the audio is expected to contain. Optional. When provided, it must\ncontain at least one supported code and cannot be `null` or empty. When omitted,\ntranscription considers all supported languages.",
                  "minItems": 1,
                  "items": {
                    "type": "string"
                  }
                },
                "fallback_language": {
                  "type": "string",
                  "description": "Language to use if Notetaker does not detect one of the `expected_languages`. Optional.\nWhen `expected_languages` is set, the fallback must be one of those codes. When\n`expected_languages` is omitted, transcription considers all supported languages and\nthe fallback may be any supported code. When `fallback_language` is omitted, the\ntranscriber auto-detects the language. The field is not stored, so responses do not\nreturn it."
                },
                "keywords": {
                  "type": "array",
                  "description": "Domain-specific terms that bias transcription toward recognizing them correctly, such\nas names, acronyms, and product names. Optional. Up to 200 terms; each term must be\n1 to 200 characters and cannot contain control characters. Cannot be `null`.",
                  "maxItems": 200,
                  "items": {
                    "type": "string",
                    "maxLength": 200
                  }
                },
                "use_speaker_names_as_keywords": {
                  "type": "boolean",
                  "description": "When `true`, Notetaker adds known speaker names to the keyword set so they are\ntranscribed accurately. Optional. Cannot be `null`."
                }
              }
            }
          }
        }
      ]
    },
    "meeting_settings_common": {
      "type": "object",
      "description": "A collection of settings for the Notetaker bot.",
      "properties": {
        "action_items": {
          "type": "boolean",
          "description": "When `true`, Notetaker generates a list of action items from the meeting. If `action_items` is\n`true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.",
          "default": true
        },
        "action_items_settings": {
          "type": "object",
          "properties": {
            "custom_instructions": {
              "type": "string",
              "description": "A custom prompt to pass to Nylas' AI model and specify settings for the list of action items\nit generates. `action_items` must be `true` to use this field."
            }
          }
        },
        "audio_recording": {
          "type": "boolean",
          "description": "When `true`, Notetaker records the meeting's audio.",
          "default": true
        },
        "leave_after_silence_seconds": {
          "type": "integer",
          "description": "The number of seconds of silence after which the Notetaker bot automatically leaves\nthe meeting. This helps end recordings when meetings have concluded but participants\nhaven't disconnected the call. Must be between 10 and 3600 seconds (1 hour).",
          "minimum": 10,
          "maximum": 3600,
          "default": 300
        },
        "summary": {
          "type": "boolean",
          "description": "When `true`, Notetaker generates a summary of the meeting. If `summary` is `true`,\n`video_recording`, `audio_recording`, and `transcription` must also be `true`.",
          "default": true
        },
        "summary_settings": {
          "type": "object",
          "properties": {
            "custom_instructions": {
              "type": "string",
              "description": "A custom prompt to pass to Nylas' AI model and specify settings for the summary it generates.\n`summary` must be `true` to use this field."
            }
          }
        },
        "transcription": {
          "type": "boolean",
          "description": "When `true`, Notetaker transcribes the meeting's audio. If `transcription` is `true`,\n`video_recording` and `audio_recording` must also be `true`.",
          "default": true
        },
        "video_recording": {
          "type": "boolean",
          "description": "When `true`, Notetaker records the meeting's video.",
          "default": true
        }
      }
    },
    "metadata": {
      "title": "Metadata",
      "type": "object",
      "description": "The metadata associated with the object. For more information, see\n[Metadata](/docs/reference/api/#metadata).",
      "additionalProperties": {
        "type": "string",
        "description": "A key-value pair.",
        "maxLength": 500
      },
      "maxProperties": 50
    }
  }
}