To-do component

A To-do calendar component is a grouping of component properties, possibly including Alarm calendar components, that represents an action-item or assignment.

For example, it can be used to represent an item of work assigned to an individual; such as "turn in travel expense today".

To-dos must be sent using endpoint:

https://convier.me/api/todo

Following properties are available:

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

Unique identifier

This property defines the persistent, globally unique identifier for the to-do. 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 a to-do:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL'

As this is the first request for this to-do, 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 to-do 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/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 08:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a (nice) review for this awesome movie.' \
-d 'todo[sequence]=2' \
-d 'todo[uid]=20201225T101441Z-5fe5bb91debc4' \
-d 'todo[attendees][0][email]=USER_EMAIL'

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

{warning} To-do requests may not be well interpreted by your email servers. Check Troubleshoot documentation if you get an IMAP4 protocol error.

Class

This property defines the access classification for a to-do. This property must be a string among values public, private and confidential.

The following example shows how to create a public to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[class]=public' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Completed

This property specifies the date and time that the to-do 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 a to-do:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[created][date]=04/26/2019 08:00 PM' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Created

This property specifies the date and time that the to-do 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 a to-do:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[created][date]=04/26/2019 08:00 PM' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Description

This property specifies a complete description of the to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Start

This property specifies the date and time that an to-do 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 to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Geo

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

Attribute	Key	Definition	Mandatory	Type
Latitude	`latitude`	Latitude coordinate of the to-do	Yes	float
Longitude	`longitude`	Longitude coordinate of the to-do	Yes	float

The following example shows how to set the global position to Paris of a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[geo][latitude]=48.866667' \
-d 'todo[geo][longitude]=2.333333' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Last modification

This property specifies the date and time that the information associated with the to-do 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 a to-do:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[last_modification][date]=04/26/2019 08:00 PM' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Location

This property defines the intended venue for the to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[location][value]=Paris' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Organizer

This property defines the organizer for a to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Percent complete

This property defines the percent completion of a to-do. This property must be set as an int between 0 (to-do has not yet been started) and 100 (to-do has been completed).

The following example shows how to set the completion of a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[percent_complete]=70' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Priority

This property defines the relative priority for a to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[priority]=highest' \
-d 'todo[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 to-do. 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 to-dos every last Friday of every other month:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[recurrence_rule][frequency]=monthly' \
-d 'todo[recurrence_rule][by][day][friday]=true' \
-d 'todo[recurrence_rule][by][occurrence]=-1' \
-d 'todo[recurrence_rule][count]=3' \
-d 'todo[recurrence_rule][interval]=2' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Given these parameters, the to-do 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/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 08:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Bring the popcorn (sooner).' \
-d 'todo[sequence]=2' \
-d 'todo[uid]=20201225T101441Z-5fe5bb91debc4' \
-d 'todo[recurrence_id][date]=06/28/2019 09:00 PM' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Sequence

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

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

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 08:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[sequence]=2' \
-d 'todo[uid]=20201225T101441Z-5fe5bb91debc4' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Status

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

needs-action indicates that to-do needs action.
completed indicates that to-do is completed.
in-process indicates that to-do is in process of.
canceled indicates that to-do is canceled.

The following example shows how to set a tentative to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[status]=in-process' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Summary

This property defines a short summary or subject for the to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL'

URL

This property defines a Uniform Resource Locator (URL) associated with the to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[url]=https://en.wikipedia.org/wiki/Avengers:_Endgame' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Recurrence rule

This property defines a rule or repeating pattern for recurring to-dos. 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 to-do repeats yearly.
monthly indicates that to-do repeats monthly.
daily indicates that to-do repeats daily.
hourly indicates that to-do repeats hourly.
minutely indicates that to-do repeats minutely.
secondly indicates that to-do 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 to-dos every last Friday of every other month:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[recurrence_rule][frequency]=monthly' \
-d 'todo[recurrence_rule][by][day][friday]=true' \
-d 'todo[recurrence_rule][by][occurrence]=-1' \
-d 'todo[recurrence_rule][count]=3' \
-d 'todo[recurrence_rule][interval]=2' \
-d 'todo[attendees][0][email]=USER_EMAIL'

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

Due

This property defines the date and time that a to-do is expected to be completed. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Duration

This property specifies a duration for the to-do. 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 to-do request starting from April 26, 2019, at 09:00 PM:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL' \
-d 'todo[duration][days]=3'

Attachments

This property provides the capability to associate document objects with a to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attachments][0][url]=ftp://example.com/pub/reports/r-960812.ps' \
-d 'todo[attachments][0][format]=application/postscript' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Attendees

This property specifies participants, non-participants, and the chair of a to-do. 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 to-do.
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 to-do needs action.
accepted indicates that to-do is accepted.
declined indicates that to-do is declined.
tentative indicates that to-do is tentatively accepted.
delegated indicates that to-do is delegated.
completed indicates that to-do is completed.
in-process indicates that to-do is in process of being completed.

The following example shows how to attach a report to a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][type]=individual' \
-d 'todo[attendees][0][role]=required-participant' \
-d 'todo[attendees][0][participation]=accepted' \
-d 'todo[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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL' \
-d 'todo[comments][0][value]=This movie is great!' \
-d 'todo[comments][0][language]=en'

Contacts

This property is used to represent contact information or alternately a reference to contact information associated with the to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL' \
-d 'todo[contacts][0][value]=Jarvis'

Exception dates

This property defines the list of date-time exceptions for recurring to-dos. 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 to-dos beginning every last Friday of every other month:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[recurrence_rule][frequency]=monthly' \
-d 'todo[recurrence_rule][by][day][friday]=true' \
-d 'todo[recurrence_rule][by][occurrence]=-1' \
-d 'todo[recurrence_rule][count]=3' \
-d 'todo[recurrence_rule][interval]=2' \
-d 'todo[exception_dates][date]=06/28/2019 09:00 PM' \
-d 'todo[attendees][0][email]=USER_EMAIL'

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

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 to-do is a superior of the referenced calendar component.
sibling indicates that the to-do is a peer of the referenced calendar component.
parent indicates that the to-do is a subordinate of the referenced calendar component.

The following example shows how to set a to-do as child of another to-do:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[related][0][to]=20201225T101441Z-5fe5bb91debc4' \
-d 'todo[related][0][type]=child' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Resources

This property defines the equipment or resources anticipated for a to-do. 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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[attendees][0][email]=USER_EMAIL' \
-d 'todo[resources][values][0]=PROJECTOR' \
-d 'todo[resources][values][1]=VCR' \
-d 'todo[resources][language]=en'

Recurrence dates

This property defines the list of date-time values for recurring to-dos. 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 to-do by setting the recurrence dates:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[recurrence_dates][0][date]=06/28/2019 09:00 PM' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Color

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

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

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[color]=red' \
-d 'todo[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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[conferences][0][uri]=https://en.wikipedia.org/wiki/Videotelephony' \
-d 'todo[conferences][0][features][0]=audio' \
-d 'todo[conferences][0][features][1]=video' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Images

This property specifies an image associated with the to-do. 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 to-do.
graphic displays a full image replacement for the to-do itself.
fullsize displays an image that is used to enhance the to-do.
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 a to-do request:

curl https://convier.me/api/todo \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[images][0][uri]=https://upload.wikimedia.org/wikipedia/en/0/0d/Avengers_Endgame_poster.jpg' \
-d 'todo[images][0][display]=thumbnail' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Alarms

This property provides a grouping of component properties that is a reminder or alarm for a to-do. 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 a to-do 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 to-do.

{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 to-do begins:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'todo[start][date]=04/26/2019 09:00 PM' \
-d 'todo[due][date]=04/28/2019 09:00 PM' \
-d 'todo[organizer][name]=Tony Stark' \
-d 'todo[organizer][email]=ironman@avengers.com' \
-d 'todo[summary][value]=Endgame review' \
-d 'todo[description][value]=Write a review for this awesome movie.' \
-d 'todo[alarms][0][action]=display' \
-d 'todo[alarms][0][trigger][related_to_start]=true' \
-d 'todo[alarms][0][trigger][duration][minutes]=5' \
-d 'todo[alarms][0][description]=It is time to start writing.' \
-d 'todo[attendees][0][email]=USER_EMAIL'

Documentation

API Reference

To-do component

Unique identifier

Class

Completed

Created

Description

Start

Geo

Last modification

Location

Organizer

Percent complete

Priority

Recurrence Id

Sequence

Status

Summary

URL

Recurrence rule

Due

Duration

Attachments

Attendees

Categories

Comments

Contacts

Exception dates

Related

Resources

Recurrence dates

Color

Conferences

Images

Alarms