User manual

• Introduction
• Authentication
• Requests
• Responses
• Errors
• Troubleshoot

Introduction

Convier is a REST API which allows users to exchange calendaring and scheduling information such as events, to-dos and journal entries directly in your users' calendars.. Generated requests comply with the iCalendar RFC 5545 standard and supports RFC 7986 and RFC 7953 extensions.

{primary} Integration packages to facilitate the integration of Convier API into your application are under development and should be available soon.

We recommend the use of Insomnia or Postman software to become familiar with the features of the API.

Authentication

The Convier API uses API tokens to authenticate requests. You can view and manage your API tokens in your Dashboard. Authentication to the API is performed via Bearer Auth using cURL headers:

-H 'Authorization: Bearer YOUR_TOKEN'

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Requests

All API requests use the base URL:

https://convier.me/api

Requests must be made using endpoints:

Each request must be defined with the following parameters:

The calendar attribute is furthermore described in the Calendar section of API reference.

{info} The download attribute allows to retrieve the text generated request in the API response. This feature is only available for the Enterprise subscription plan.

The email attribute allows to customize the email send to attendees. This attribute must be set as an array with children attributes:

{info} Customize email feature is only available for the Startup and the Enterprise subscription plan.

The following example shows how to create an event request with customized email content:

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

The calendar components are described in the API reference. See Event, To-do and Journal for full documentation of these components.

Responses

The API returns JSON responses with attributes:

{info} The uid attribute can be used to create update requests later.

{info} The data attribute contains the textual version of the generated calendar request. This feature is only available for the Enterprise subscription plan.

Errors

Convier uses conventional HTTP response codes to indicate the success or failure of an API request:

Troubleshoot

Several users have reported that some email clients do not fully support the iCalendar format. We have summarised the compatibility information we currently have in the following table:

You may also encounter an error when retrieving (over an IMAP protocol) a request with the following message:

Retrieval failed using IMAP4 protocol for message.

This is usually due to Microsoft Exchange server trying to automatically process the request. This can be fixed using one of the solutions described below:

• If you have access to the server, you should be able to disable this behavior by entering the following command in a terminal:

  Set-MailboxCalendarSettings -Identity "Username" -AutomateProcessing None

• If you do not have access to the server:
  • Check that you have set the calendar method attribute to request. Other values seem to generate an error.
  • Try to set email attach to true and email inline to false. Generated requests will be sent as an attachment, which should be processed automatically by the client (see Table above) or manually by the user.

For any other errors not listed here, a community support is available.

{info} Dedicated support is available for the Startup and the Enterprise subscription plan.