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'

Categories

This property is used to specify categories or subtypes of the 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

The following example shows how to set categories 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[categories][values][0]=APPOINTMENT' \
-d 'todo[categories][values][1]=EDUCATION' \
-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.

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 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'