Event component

---

• Unique identifier
• Start
• Class
• Created
• Description
• Geo
• Last modification
• Location
• Organizer
• Priority
• Sequence
• Status
• Summary
• Transparency
• URL
• Recurrence Id
• Recurrence rule
• End
• Duration
• Attachments
• Attendees
• Categories
• Comments
• Contacts
• Exception dates
• Related
• Resources
• Recurrence dates
• Color
• Conferences
• Images
• Alarms

An Event calendar component is a grouping of component properties, possibly including Alarm calendar components, that represents a scheduled amount of time on a calendar.

For example, it can be an activity; such as a one-hour-long, department meeting from 8:00 AM to 9:00 AM, tomorrow.

Events must be sent using endpoint:

https://convier.me/api/event

Following properties are available:

Property	Key	Definition	Mandatory	Type
Unique identifier	unique_identifier	Persistent, globally unique identifier of the event	No	string
Start	start	Start date and time for the event	Yes	array
Class	class	Access classification for the event	No	string
Created	created	Date and time of the creation of the event	No	string
Description	description	Complete description of the event	No	array
Geo	geo	Latitude and longitude of the event	No	array
Last modification	last_modification	Date and time of the last revision of the event	No	string
Location	location	Intended venue of the event	No	string
Organizer	organizer	Organizer of the event	No	array
Priority	priority	Relative priority for the to-do	No	string or int
Sequence	sequence	Revision sequence number of the event	No	int
Status	status	Overall status or confirmation for the event	No	array
Summary	summary	Short summary or subject for the event	No	array
Transparency	transparency	Transparency to busy time searches	No	array
URL	url	Uniform Resource Locator (URL) associated with the event	No	array
Recurrence Id	recurrence_id	Specific instance of a recurring event	No	array
Recurrence rule	recurrence_rule	Rule or repeating pattern for recurring events	No	array
End	end	Date and time by which the event ends	No	array
Duration	duration	Duration of the event	No	array
Attachments	attachments	Associates a document with the event	No	array
Attendees	attendees	Participants, non-participants, and the chair of the event	No	array
Categories	categories	Categories or subtypes of the event	No	array
Comments	comments	Comments to the user	No	array
Contacts	contacts	Contacts information for the event	No	array
Exception dates	exception_dates	List of date-time exceptions for recurring events	No	array
Related	related	Relationship or reference between components	No	array
Resources	resources	Equipment or resources anticipated for the event	No	array
Recurrence dates	recurrence_dates	List of date-time values for recurring events	No	array
Color	color	Color used for displaying the event	No	string
Conferences	conferences	Information for accessing conferencing systems	No	array
Images	images	Images associated with the event	No	array
Alarms	alarms	Reminder or alarm for the event	No	array

Unique identifier

This property defines the persistent, globally unique identifier for the event. This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests.

{info} This property is only available for Enterprise subscription plan.

For example, let's say you have created a request for an event:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL'

As this is the first request for this event, Convier automatically generates an UID for you. This UID is included in the API response:

{
    "error": false, 
    "message": null, 
    "uid": 20201225T101441Z-5fe5bb91debc4, 
    "data": null
}

Now suppose you need to update the event information, you can then make a new request to the API by setting the UID property (with the previously returned value) and increase a new value for the sequence property:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 08:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn (sooner).' \
-d 'event[sequence]=2' \
-d 'event[uid]=20201225T101441Z-5fe5bb91debc4' \
-d 'event[attendees][0][email]=USER_EMAIL'

The user calendar client should then offer to update the previously accepted event.

Start

This property specifies the date and time that an event begins. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	Start date and time	Yes	string
Timezone Id	timezone_id	Timezone database name	No	string
Local time	use_local_time	Defines whether the date is expressed in the local base time of the user's calendar	No	bool

{warning} The date attribute must be specified as an English textual datetime.

{info} If use_local_time is not set, the date is by default expressed in UTC.

The following example shows how to set the start date and time of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL'

Class

This property defines the access classification for an event. This property must be a string among values public, private and confidential.

The following example shows how to create a public event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[class]=public' \
-d 'event[attendees][0][email]=USER_EMAIL'

Created

This property specifies the date and time that the event was created. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	End date and time	Yes	string

{warning} The date attribute must be specified as an English textual datetime.

The following example shows how to set the creation date of an event:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[created][date]=04/26/2019 08:00 PM' \
-d 'event[attendees][0][email]=USER_EMAIL'

Description

This property specifies a complete description of the event. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Value	value	Value of description	Yes	string
Language	language	ISO 639-1 language code for value	No	string
Alternate	alternate	URI that points to an alternate representation for the value	No	string

The following example shows how to set the description of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL'

Geo

This property specifies information related to the global position of the event. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Latitude	latitude	Latitude coordinate of the event	Yes	float
Longitude	longitude	Longitude coordinate of the event	Yes	float

The following example shows how to set the global position to Paris of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[geo][latitude]=48.866667' \
-d 'event[geo][longitude]=2.333333' \
-d 'event[attendees][0][email]=USER_EMAIL'

Last modification

This property specifies the date and time that the information associated with the event was last revised. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	End date and time	Yes	string

{warning} The date attribute must be specified as an English textual datetime.

The following example shows how to set the last modification date of an event:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[last_modification][date]=04/26/2019 08:00 PM' \
-d 'event[attendees][0][email]=USER_EMAIL'

Location

This property defines the intended venue for the event. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Value	value	Value of location	Yes	string
Language	language	ISO 639-1 language code for value	No	string
Alternate	alternate	URI that points to an alternate representation for the value	No	string

The following example shows how to set the location to Paris of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[location][value]=Paris' \
-d 'event[attendees][0][email]=USER_EMAIL'

Organizer

This property defines the organizer for an event. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Email	email	Email address	Yes	string
Name	name	Common name	No	string

`

{warning} The email attribute must be a valid email address following RFC 822.

The following example shows how to set the organizer of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL'

Priority

This property defines the relative priority for an event. This property must be set as a string among values highest and lowest, or as an int between 1 (high priority) and 9 (low priority).

The following example shows how to set the highest priority of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[priority]=highest' \
-d 'event[attendees][0][email]=USER_EMAIL'

Sequence

This property defines the revision sequence number of the event. You must increment (starting from 0) the value of this property each time you update the information of an event. This property must be set as an int.

The following example shows how to set the sequence of an updated event:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 08:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[sequence]=2' \
-d 'event[uid]=20201225T101441Z-5fe5bb91debc4' \
-d 'event[attendees][0][email]=USER_EMAIL'

Status

This property defines the overall status or confirmation for the event. This property must be set as a string among values:

• canceled indicates that event was cancelled.
• confirmed indicates that event is definite.
• tentative indicates that event is tentative.

The following example shows how to set a tentative event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[status]=tentative' \
-d 'event[attendees][0][email]=USER_EMAIL'

Summary

This property defines a short summary or subject for the event. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Value	value	Value of summary	Yes	string
Language	language	ISO 639-1 language code for value	No	string
Alternate	alternate	URI that points to an alternate representation for the value	No	string

The following example shows how to set the summary of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL'

Transparency

This property defines whether an event is transparent to busy time searches. This property must be set as a string among values:

• opaque indicates that event will appear to consume time on user's calendar.
• transparent indicates that event will not appear consume time on user's calendar.

The following example shows how to set an opaque event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[transparency]=opaque' \
-d 'event[attendees][0][email]=USER_EMAIL'

URL

This property defines a Uniform Resource Locator (URL) associated with the event. This property must be set as a string.

{warning} The value of this attribute must be a valid URI following RFC 3986.

The following example shows how to set the URL of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[url]=https://en.wikipedia.org/wiki/Avengers:_Endgame' \
-d 'event[attendees][0][email]=USER_EMAIL'

Recurrence Id

This property is used in conjunction with the uid and sequence properties to identify (and update) a specific instance of a recurring event. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	Date of the occurrence	Yes	string
Include subsequent occurrences	include_subsequent	Include subsequent occurrences	No	bool

{info} The include_subsequent attribute allows selecting all occurrences starting from date defined by the date attribute.

Let's say you have previously created to a request for three recurring events every last Friday of every other month:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[recurrence_rule][frequency]=monthly' \
-d 'event[recurrence_rule][by][day][friday]=true' \
-d 'event[recurrence_rule][by][occurrence]=-1' \
-d 'event[recurrence_rule][count]=3' \
-d 'event[recurrence_rule][interval]=2' \
-d 'event[attendees][0][email]=USER_EMAIL'

Given these parameters, the event will repeat itself the April 26, 2019, June 28, 2019, and the August 30, 2019.

The following example shows how to create a request to update only the June 28, 2019, occurrence:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 08:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn (sooner).' \
-d 'event[sequence]=2' \
-d 'event[uid]=20201225T101441Z-5fe5bb91debc4' \
-d 'event[recurrence_id][date]=06/28/2019 09:00 PM' \
-d 'event[attendees][0][email]=USER_EMAIL'

Recurrence rule

This property defines a rule or repeating pattern for recurring events. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Frequency	frequency	Frequency of the recurrence	Yes	string
By	by	Parameters of the recurrence	No	array
Interval	interval	Interval of the recurrence	No	int
Count	count	Number of occurrences	No	int
Until date	until	End date of the recurrence	No	array
Parameters selection	occurrence	Selects a given parameter of the recurrence	No	int
Occurrence selection	use_value_in_list	Selects a given occurrence	No	int
Start of the week	monday_as_week_start	Set monday as the first day of the week	No	bool

{info} The interval attribute represents at which intervals the recurrence rule repeats. The default value is 1, meaning every second when frequency attribute is set to secondly, every minute when the frequency attribute is set to minutely and so on.

{info} The count attribute represents the number of times the recurrence rule repeats.

The frequency attribute must be set as a string among values:

• yearly indicates that event repeats yearly.
• monthly indicates that event repeats monthly.
• daily indicates that event repeats daily.
• hourly indicates that event repeats hourly.
• minutely indicates that event repeats minutely.
• secondly indicates that event repeats secondly.

The by attribute is an array describing the recurrence with child attributes:

• day is a list of days when recurrence applies. This attribute must be set as a bool array with keys among monday, tuesday, wednesday, thursday, friday, saturday and sunday and values set to true or false to select the day.
• month is a list of months when recurrence applies. This attribute must be set as a bool array with keys january, february, march, april, may, june, july, august, september, october, november and december and values set to true or false to select the month.
• month_day indicates the day of the month when recurrence applies. This attribute must be set as an int between -31 and 31 excluding 0. Negative value indicates a recurrence starting from the end of the month. For example, -1 selects the last day of the month.
• year_day indicates the day of the year when recurrence applies. This attribute must be set as an int between -366 and 366 excluding 0. Negative value indicates a recurrence starting from the end of the year. For example, -1 selects the last day of the year.
• work_days indicates that recurrence applies during work days. This attribute must be set as a bool.
• week indicates the week when recurrence applies. This attribute must be set as an int between -53 and 53 excluding 0. Negative value indicates a recurrence starting from the end of the year. For example, -1 selects the last week of the year.
• minute indicates the minute when recurrence applies. This attribute must be set as an int between 0 and 59.
• hour indicates the hour when recurrence applies. This attribute must be set as an int between 0 and 23.
• second indicates the second when recurrence applies. This attribute must be set as an int between 0 and 59.

{info} The use_value_in_list attribute selects the nth occurrence among the occurrences described by the other parameters. This attribute can be positive or negative. For example, selecting the last monday of the month can be by setting frequency to monthly, [by][day][monday] to true, and use_value_in_list to -1.

{info} The occurrence attribute combined with [by][day] or [by][work_days] attributes selects the nth occurrence of the period. This attribute must be set as an int and can be both positive and negative. Negative value indicates a recurrence starting from the end of the period. For example, setting frequency to monthly, [by][day][monday] to true and occurrence to 2 selects the second monday of each month while setting occurrence to -1 selects the last monday of each month.

The until attribute must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	End date and time of recurrence	Yes	string
Local time	use_local_time	Defines whether the date is expressed in the local base time of the user's calendar	No	bool

{warning} The date attribute must be specified as an English textual datetime.

{info} If use_local_time is not set, the date is by default expressed in UTC.

The following example shows how to create a request for three recurring events every last Friday of every other month:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[recurrence_rule][frequency]=monthly' \
-d 'event[recurrence_rule][by][day][friday]=true' \
-d 'event[recurrence_rule][by][occurrence]=-1' \
-d 'event[recurrence_rule][count]=3' \
-d 'event[recurrence_rule][interval]=2' \
-d 'event[attendees][0][email]=USER_EMAIL'

Given these parameters, the event will repeat itself the April 26, 2019, June 28, 2019, and the August 30, 2019.

End

This property specifies the date and time that an event ends. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	End date and time	Yes	string
Timezone Id	timezone_id	Timezone database name	No	string
Local time	use_local_time	Defines whether the date is expressed in the local base time of the user's calendar	No	bool

{warning} The date attribute must be specified as an English textual datetime.

{info} If use_local_time is not set, the date is by default expressed in UTC.

The following example shows how to set the end date and time of an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL'

Duration

This property specifies a duration for the event. This property must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Days	days	Duration in days	Yes	int
Weeks	weeks	Duration in weeks	Yes	int
Positivity	positivity	Defines a positive of negative duration	No	bool

Both days and weeks attributes can appear at the same time.

{info} If positivity is not set, the duration is by default positive.

The following example shows how to define a three days event request starting from April 26, 2019, at 09:00 PM:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL' \
-d 'event[duration][days]=3'

Attachments

This property provides the capability to associate document objects with an event. This property must be set as an array of attachment, each attachment must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
URI	uri	URI that points to a document object	Yes	string
File	file	URI that points to a document object to embed	Yes	string
Format	format	Format of the document object	No	string

The uri and file attributes cannot appear at the same time. Both point to a document object, but file will read the document and embed its binary content in the request. If the uri is specified, the format attribute can also be specified to indicate the media (MIME) type.

{warning} The uri attribute must be a valid URI following RFC 3986.

The following example shows how to attach a report to an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attachments][0][url]=ftp://example.com/pub/reports/r-960812.ps' \
-d 'event[attachments][0][format]=application/postscript' \
-d 'event[attendees][0][email]=USER_EMAIL'

Attendees

This property specifies participants, non-participants, and the chair of an event. This property must be set as an array of attendee, each attendee must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Email	email	Email address	Yes	string
Name	name	Common name	No	string
Type	type	Type of calendar user	No	string
Memberships	memberships	Groups that the attendee belongs to	No	string array
Role	role	Intended role	No	string
Participation	participation	Status of the attendee’s participation	No	string
Dir	dir	URI that points to the directory information of attendee	No	string
Language	language	ISO 639-1 language code for values	No	string
Sent by	sent_by	Indicates whom is acting on behalf of the attendee	No	string array
Reply requested	reply_requested	Reply is requested	No	bool
Delegated to	delegated_to	Indicates the calendar users that the original request was delegated to	No	string array
Delegated from	delegated_from	Indicates whom the request was delegated from	No	string array

{warning} The email attribute must be a valid email address following RFC 822.

{warning} The dir attribute must be a valid URI following RFC 3986.

The type attribute must be set as a string among values:

• individual indicates an individual.
• group indicates a group of individuals.
• resource indicates a physical resource.
• room indicates a room resource.
• unknown indicates an unknown resource.

The role attribute must be set as a string among values:

• chair indicates chair of the event.
• required-participant indicates a participant whose participation is required.
• optional-participant indicates a participant whose participation is optional.
• non-participant indicates a participant who is copied for information purposes only.

The participation attribute must be set as a string among values:

• needs-action indicates that event needs action.
• accepted indicates that event is accepted.
• declined indicates that event is declined.
• tentative indicates that event is tentatively accepted.

The following example shows how to attach a report to an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][type]=individual' \
-d 'event[attendees][0][role]=required-participant' \
-d 'event[attendees][0][participation]=accepted' \
-d 'event[attendees][0][email]=USER_EMAIL'

Categories

This property is used to specify categories or subtypes of the event. This property must be set as an array of with children attributes:

Attribute	Key	Definition	Mandatory	Type
Values	values	Values of resources	Yes	string array
Language	language	ISO 639-1 language code for values	No	string

The following example shows how to set categories to an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[categories][values][0]=APPOINTMENT' \
-d 'event[categories][values][1]=EDUCATION' \
-d 'event[attendees][0][email]=USER_EMAIL'

Comments

This property specifies non-processing information intended to provide comments to the calendar user. This property must be set as an array of comment, each comment must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Value	value	Value of comment	Yes	string
Language	language	ISO 639-1 language code for value	No	string
Alternate	alternate	URI that points to an alternate representation for the value	No	string

The following example shows how to add a comment to an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL' \
-d 'event[comments][0][value]=This movie is great!' \
-d 'event[comments][0][language]=en'

Contacts

This property is used to represent contact information or alternately a reference to contact information associated with the event. This property must be set as an array of contact, each contact must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Value	value	Value of contact	Yes	string
Language	language	ISO 639-1 language code for value	No	string
Alternate	alternate	URI that points to an alternate representation for the value	No	string

The following example shows how to add a contact to an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL' \
-d 'event[contacts][0][value]=Jarvis'

Exception dates

This property defines the list of date-time exceptions for recurring events. This property must be set as an array of exception date, each exception date must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	Start date and time	Yes	string
Local time	use_local_time	Defines whether the date is expressed in the local base time of the user's calendar	No	bool

{warning} The date attribute must be specified as an English textual datetime.

{info} If use_local_time is not set, the date is by default expressed in UTC.

The following example shows how to add an exception for three recurring events beginning every last Friday of every other month:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[recurrence_rule][frequency]=monthly' \
-d 'event[recurrence_rule][by][day][friday]=true' \
-d 'event[recurrence_rule][by][occurrence]=-1' \
-d 'event[recurrence_rule][count]=3' \
-d 'event[recurrence_rule][interval]=2' \
-d 'event[exception_dates][date]=06/28/2019 09:00 PM' \
-d 'event[attendees][0][email]=USER_EMAIL'

Given these parameters, the event will repeat itself only the April 26, 2019, and the August 30, 2019.

Related

This property is used to represent a relationship or reference between one calendar component and another. This property must be set as an array of relationship, each relationship must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
To	to	UID of another calendar component	Yes	string
Type	type	Type of relationship	No	string

The type attribute must be set as a string among values:

• child indicates that the event is a superior of the referenced calendar component.
• sibling indicates that the event is a peer of the referenced calendar component.
• parent indicates that the event is a subordinate of the referenced calendar component.

The following example shows how to set an event as child of another event:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[related][0][to]=20201225T101441Z-5fe5bb91debc4' \
-d 'event[related][0][type]=child' \
-d 'event[attendees][0][email]=USER_EMAIL'

Resources

This property defines the equipment or resources anticipated for an event. This property must be set as an array of with children attributes:

Attribute	Key	Definition	Mandatory	Type
Values	values	Values of resources	Yes	string array
Language	language	ISO 639-1 language code for values	No	string
Alternate	alternate	URI that points to an alternate representation for the values	No	string

The following example shows how to set resources for an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[attendees][0][email]=USER_EMAIL' \
-d 'event[resources][values][0]=PROJECTOR' \
-d 'event[resources][values][1]=VCR' \
-d 'event[resources][language]=en'

Recurrence dates

This property defines the list of date-time values for recurring events. This property must be set as an array of recurrence date, each recurrence date must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Date	date	Recurrence date and time	Yes	string
Local time	use_local_time	Defines whether the date is expressed in the local base time of the user's calendar	No	bool
Period	period	Period of time	Yes	array

{info} Recurrence dates can be set explicitly using the date attribute or implicitly if they fall within a period of time defined by the period attribute. Attributes date and period cannot be both set.

The period attribute is an array describing a period of time with child attributes:

• start is the start datetime of the period. This attribute must be set as a string and must be specified as an English textual datetime.
• end is the end datetime of the period. This attribute must be set as a string and must be specified as an English textual datetime.
• duration is the duration of the period.

The duration attribute is an array describing the duration of the period with child attributes:

• weeks defines the duration in weeks. This attribute must be set as an int.
• days defines the duration in days. This attribute must be set as an int.
• minutes defines the duration in minutes. This attribute must be set as an int.
• hours defines the duration in hours. This attribute must be set as an int.
• seconds defines the duration in seconds. This attribute must be set as an int.

The following example shows how to create a recurrent event by setting the recurrence dates:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[recurrence_dates][0][date]=06/28/2019 09:00 PM' \
-d 'event[attendees][0][email]=USER_EMAIL'

Color

This property specifies a color used for displaying the event. This property must be a string and should be a valid CSS3 color name.

The following example shows how to create an event that will be displayed in red on the user's calendar:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[color]=red' \
-d 'event[attendees][0][email]=USER_EMAIL'

Conferences

This property specifies information for accessing a conferencing system. This property must be set as an array of conference, each conference must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
URI	uri	Access URI	Yes	string
Label	label	Additional details on the use of the system	No	string
Language	language	ISO 639-1 language code for value	No	string
Features	features	Features of system	No	string array

{warning} The uri attribute must be a valid URI following RFC 3986.

The features attribute is a string array describing the features available on the conference system among following values:

• audio describes audio capability.
• screen describes screen sharing.
• video describes video capability.
• chat describes chat or instant messaging.
• feed describes blog or Atom feed.
• moderator describes moderator dial-in code.
• phone describes phone conference.

The following example shows how to attach a conference system with audio and video functionality to an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[conferences][0][uri]=https://en.wikipedia.org/wiki/Videotelephony' \
-d 'event[conferences][0][features][0]=audio' \
-d 'event[conferences][0][features][1]=video' \
-d 'event[attendees][0][email]=USER_EMAIL'

Images

This property specifies an image associated with the event. This property must be set as an array of image, each image must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
URI	uri	URI that points to an image	Yes	string
Display	display	Intended display modes for the image	No	string array
File	file	URI that points to an image to embed	Yes	string
Format	format	Format of the image	No	string

The display attribute is a string array describing display modes of the image among following values:

• badge displays image inline with the title of the event.
• graphic displays a full image replacement for the event itself.
• fullsize displays an image that is used to enhance the event.
• thumbnail displays a smaller variant of fullsize to be used when space for the image is constrained.

The uri and file attributes cannot appear at the same time. Both point to an image, but file will read the image and embed its binary content in the request. If the uri is specified, the format attribute can also be specified to indicate the media (MIME) type.

{warning} The uri attribute must be a valid URI following RFC 3986.

The following example shows how to add an image to an event request:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[images][0][uri]=https://upload.wikimedia.org/wikipedia/en/0/0d/Avengers_Endgame_poster.jpg' \
-d 'event[images][0][display]=thumbnail' \
-d 'event[attendees][0][email]=USER_EMAIL'

Alarms

This property provides reminders or alarms for an event. This property must be set as an array of alarm, each alarm must furthermore be an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Action	action	Type of action invoked when the alarm is triggered	Yes	string
Description	description	Description of the alarm	Yes	array
Trigger	trigger	Specifies when the alarm will be triggered	Yes	array
Summary	summary	Text to be used as the message subject	Yes	array
Attendees	attendees	Attendees that receive the message	No	array
Duration	duration	Delay period after which the alarm will repeat	No	array
Repeat	repeat	Number of additional repetitions	No	int
Attachments	attachments	URI that points to resources	No	array

The action attribute specifies the type of action invoked when the alarm is triggered. It must be set as a string among values:

• display indicates that a text will be displayed when the alarm is triggered.
• audio indicates that a sound will be rendered when the alarm is triggered.
• email indicates that an email message will be sent when the alarm is triggered.

This description attribute specifies a complete description of the alarm. It must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Value	value	Value of description	Yes	string
Language	language	ISO 639-1 language code for value	No	string
Alternate	alternate	URI that points to an alternate representation for the value	No	string

{info} The description attribute is optional for an audio action.

The trigger attribute specifies when the alarm will be triggered. It defines a duration prior to the start or the end of an event and must be set as an array with child attributes:

• date defines a datetime at which the alarm will be trigger. This attribute must be set as a string.
• duration defines a period of time after which the alarm will be triggered. This attribute must be set as an array.
• related_to_start indicates that alarm will be triggered relative to start attribute of event. This attribute must be set as a bool.
• related_to_end indicates that alarm will be triggered relative to end attribute of event. This attribute must be set as a bool.

{info} If related_to_start and related_to_end are not set, the alarm will be triggered, by default, relative to the start of the event.

{warning} The date attribute must be specified as an English textual datetime.

The duration attribute of trigger attribute is an array describing the trigger's duration with child attributes:

• weeks defines the duration in weeks. This attribute must be set as an int.
• days defines the duration in days. This attribute must be set as an int.
• minutes defines the duration in minutes. This attribute must be set as an int.
• hours defines the duration in hours. This attribute must be set as an int.
• seconds defines the duration in seconds. This attribute must be set as an int.

The summary defines a short summary or subject for the alarm. This attribute must be set as an array with children attributes:

Attribute	Key	Definition	Mandatory	Type
Value	value	Value of summary	Yes	string
Language	language	ISO 639-1 language code for value	No	string
Alternate	alternate	URI that points to an alternate representation for the value	No	string

{info} The summary attribute is optional for an audio, or a display action.

The attendees attribute defines a list of attendees that will receive the email when the alarm is triggered. See attendees attribute definition.

The duration attribute is an array describing the delay period, after which the alarm will repeat. This attribute must be set as an array with child attributes:

• weeks defines the duration in weeks. This attribute must be set as an int.
• days defines the duration in days. This attribute must be set as an int.
• minutes defines the duration in minutes. This attribute must be set as an int.
• hours defines the duration in hours. This attribute must be set as an int.
• seconds defines the duration in seconds. This attribute must be set as an int.

The attachments attribute defines a list of resources. It can be a URI that points to an audio resource for audio action, or to a document object of an email action. See attachments attribute definition.

{info} The attachments attribute is optional for an audio, or a display action.

The following example shows how to set an alarm that will be triggered 5 minutes before the event begins:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'event[alarms][0][action]=display' \
-d 'event[alarms][0][trigger][related_to_start]=true' \
-d 'event[alarms][0][trigger][duration][minutes]=5' \
-d 'event[alarms][0][description]=You are late.' \
-d 'event[attendees][0][email]=USER_EMAIL'