Skip to content
Skip to main content
PUT
/v3/grants/{grant_id}/events/{event_id}

Update an event

Updates the specified event, conference, or metadata.

When you make a PUT request, Nylas replaces all data in the nested object with the information included in your request. For more information, see Updating objects.

Limitations

Nylas handles updating and deleting events similarly to other endpoints, with the following restrictions:

  • You can't update events where read_only is true.
  • You can't update events where the parent calendar's read_only field is true.
NYLAS API KEYACCESS TOKEN

Parameters

Path parameters

grant_id*string

ID of the grant to access. You can also use the email address associated with the grant, or use /me/ to refer to the grant associated with an access token.

event_id*string

ID of the event to access. Nylas recommends you URL-encode this field, or you might receive a 404 error if the ID contains special characters (for example, #).

Query parameters

calendar_id*string

The calendar ID of the event.

For Microsoft, we do not validate whether the given calendar ID matches the real calendar ID of the event. This is due to a limitation of the Microsoft Graph API.

(Not supported for iCloud) You can use primary to query the user's primary calendar.

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

notify_participantsboolean

Filter for events matching the specified notify_participants setting.

Microsoft and iCloud do not support notify_participants=false.

Default: true
tentative_as_busyboolean

(Microsoft and EWS only) When true, Nylas treats tentative events as busy.

Default: true

Request body

busybooleannull

When true, shows the event's time block as "busy" on shared or public calendars. This might be called "transparency" in some systems. This field may be null if not explicitly set. Treat null the same as true (the default behavior).

Example: true
capacityinteger

The maximum number of participants that can attend the event.

Example: 5
conferencingobject

An object that lets you automatically create a conference, or enter conferencing details manually.

You can't use autocreate and details in the same request. If you do, Nylas returns an error.

Nylas stores conference information in the event description. To remove conference details, set conferencing to {} and remove the corresponding conference information from the description in the same request.

descriptionstring

A brief description of the event (for example, its agenda). Nylas might return the description as an HTML string, depending on how the provider formats it.

For Google accounts, this field accepts a maximum of 8,192 characters.

Example: "Come ready to talk philosophy!"
hide_participantsboolean

When true, hides the event's list of participants.

Example: false
locationstring

The location of the event (for example, a physical address or the name of a meeting room).

Example: "Room 130"
maxLength: 255
metadataobject

The metadata associated with the object. For more information, see Metadata.

notetakerobject
participantsarray<object>
resourcesarray<object>
recurrencearray<string>

An array of RRULE and EXDATE strings. Nylas includes this field only if the event is the main (master) event. See RFC-5545 for more details. You can use this tool to learn more about the RRULE spec.

Events inherit their timezone from the when object. Nylas recommends that you use the when object to specify the event's start and end time.

Provider specifics:

  • On some providers, EXDATE might not include exception or cancelled event timestamps. When this happens, Nylas represents those event instances as separate objects in its responses.
  • Virtual calendars don't support DTSTART or TZID.
  • iCloud accounts do not support changing an event from recurring to non-recurring. You can create, update, or delete information on recurring events.
  • Microsoft Graph adds one day to the UNTIL date.
Example: ["RRULE:FREQ=WEEKLY;BYDAY=MO","EXDATE:20210405T000000Z"]
remindersobject

A list of reminders to send for the event. If left empty or omitted, the event uses the provider defaults.

titlestring

The name of the event.

Example: "Annual Philosophy Club Meeting"
maxLength: 1024
visibilitystringnull

(Not supported for iCloud events) Specifies whether the event is public or private. If not defined, Nylas uses the account's default provider settings. For Google and Microsoft, event visibility is public by default.

For 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.

defaultprivatepublic
when*object

An object that represents the time and duration of an event.

You can format when as one of four sub-objects: time, timespan, date, or datespan. These sub-objects allow you to capture and represent specific points in time.

time and timespan objects include optional timezone support.

Responses

request_idstring

The request ID.

dataobject
PUThttps://api.us.nylas.com/v3/grants/leyah%40example.com/events/{event_id}?notify_participants=true&tentative_as_busy=true

Find your API key in the Nylas Dashboard under API Keys in your application settings.

grant_idrequiredstring

ID of the grant to access. You can also use the email address associated with the grant, or use /me/ to refer to the grant associated with an access token.

event_idrequiredstring

ID of the event to access. Nylas recommends you URL-encode this field, or you might receive a `404` error if the ID contains special characters (for example, #).

calendar_idrequiredstring

The calendar ID of the event. For Microsoft, we do not validate whether the given calendar ID matches the real calendar ID of the event. This is due to a limitation of the Microsoft Graph API. (Not supported for iCloud) You can use primary to query the user's primary calendar.

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

notify_participantsboolean

Filter for events matching the specified notify_participants setting. Microsoft and iCloud do not support notify_participants=false.

tentative_as_busyboolean

(Microsoft and EWS only) When true, Nylas treats tentative events as busy.

Loading editor...

Autocomplete and validation come from this endpoint's request schema.