Cronofy Calendar API Documentation


Introduction

The Cronofy API is designed to provide a common API over all the types of calendar we support.

You can explore the API using Postman. More information on Postman + Cronofy.

We lean on existing standards where possible in order to simplify integration for clients.

All API requests can be made with a JSON- or forms-encoded request body, though a JSON-encoded request is recommended. You should specify the Content-Type header of your requests as either application/json; charset=utf-8 or application/x-www-form-urlencoded to signal your request body is JSON- or forms-encoded, respectively.


Data Types

The API can receive requests and return responses comprising of specific data types. For brevity in the rest of the documentation, the details of these data types are recorded in this section:

String

A String is a variable length UTF-8 encoded string.

Time

A Time is represented by a ISO 8601 compliant String that is always UTC:

2014-08-05T14:30:00Z

This represents Tuesday 5th August 2014 at 2:30PM UTC.

Date

A Date is represented by a ISO 8601 compliant String with no time component:

2014-08-05

This represents Tuesday 5th August 2014.

Boolean

A Boolean has a value of true or false.

Integer

An Integer is a 32-bit signed integer.


Errors

For API responses, we use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a named calendar could not be found, etc.), and codes in the 5xx range indicate an error with our servers.

Common responses

200 OK

The request was successful.

202 Accepted

The request has been accepted for processing.

400 Bad Request

The request was refused. Only used for requesting an access token and refreshing an access token as mandated by RFC 6749.

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

402 Payment Required

The request was refused as your plan does not include the required feature.

403 Forbidden

The request was refused as the provided authorization credentials were recognized but do not grant sufficient privileges.

You will need to make an additional authorization request for the scope required for the forbidden request.

404 Not Found

The resource, such as a calendar, could not be found.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if when creating an event you omitted the required event_id field, you would receive a response like:

{
  "errors": {
    "event_id": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.

423 Locked

This is returned when we do not have credentials available for the underlying provider and the request made requires active credentials to succeed.

We will have already sent the user an email requesting they relink to give us new credentials but you may wish to prompt them to relink as well.

429 Too Many Requests

You've exceeded your rate limits. By default these are 50 requests per second and 500 requests within a 60 second window.

Your code should stop making API requests temporarily when encountering such a response.

500 Server Error

The request was unable to be processed due to an error with our servers.


Authentication

Authentication is performed via OAuth 2.0 tokens. As an API client you will be issued with a client_id and a client_secret to be used as specified in RFC 6749 to retrieve access tokens in order to perform actions on behalf of a user.

Access Tokens MUST be passed with each API request as a Bearer Authorization header as specified in RFC 6750.

For example:

GET /v1/calendars HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

403 Forbidden

The request was refused as the provided authorization credentials were recognized but do not grant sufficient privileges.

You will need to make an additional authorization request for the scope required for the forbidden request.


Authorization

Authorization to access a user's calendars is done via the OAuth 2.0 protocol, Specifically the "Authorization Code" version of authorization as specified in section 4.1 of RFC 6749.

Find out more in our Application Authorization Tutorial.


Requesting Authorization

In order to perform actions on behalf of a user, they must first authorize you to do so.

Authorization is received by performing the "Authorization Code" version of authorization as specified in section 4.1 of RFC 6749.

This will issue you a short-lived, single-use code that you will be able to exchange for an access_token and refresh_token for the user.

Example request URL

The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request's path for clarity.

https://app.cronofy.com/oauth/authorize
    ?response_type=code
    &client_id={CLIENT_ID}
    &redirect_uri={REDIRECT_URI}
    &scope={SCOPE}
    &state={STATE}

Request URL parameters

response_type required

Must always be code as that is the only grant type supported by Cronofy.

client_id required

The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client.

redirect_uri required

The HTTP or HTTPS URI you wish the user's authorization request decision to be redirected to.

scope required

The scope of the privileges you want the eventual access_token to grant. At least one of the following scopes must be requested:

  • create_calendar to allow Create Calendar requests
  • read_events to allow Read Events requests
    • Note that if you only want to read the events you are managing, you do not need this scope so long as you pass a only_managed parameter of true to Read Events and Create Notification Channel requests.
  • create_event to allow Create or Update Event requests
  • delete_event to allow Delete Event requests
  • read_free_busy to allow Free Busy requests
    • Note that the read_events scope implicitly includes this scope as it allows access to a higher level of information than free-busy so you do not have to request both.
  • change_participation_status to allow the Participation Status of a user in an event to be set

The format of this value is specified in section 3.3 of RFC 6749 but is a space-separated String of named scopes, eg. read_events create_event delete_event.

state optional

A value that will be returned to you unaltered along with the user's authorization request decision.

The OAuth 2.0 RFC recommends using this to prevent cross-site request forgery.

avoid_linking optional

A Boolean value that when true means we will avoid linking calendar accounts together under one set of credentials.

If not provided, defaults to false.

By default, requesting authorization ties the calendars linked by the same browser to one account. This allows you as the developer to be able to access all of the users calendars through one set of API credentials.

However, your users may sometimes use a shared computer and so you may not want the calendar accounts to be tied together. This is the kind of situation in which you would want to specify this parameter as true and we will then create a set of credentials for each calendar linked.

Response URL parameters

You will not receive a direct response to your Authorization Request, instead the user will be redirected to the REDIRECT_URI with additional querystring parameters specified.

The responses are fully specified in section 4.1.2 of RFC 6749.

Successful response

code required

A short-lived, single-use code to be used to make an Access Token Request.

Will always be 32 character String of ASCII characters.

state optional

The value you passed for the state within the authorization request.

Error response

error required

A single ASCII error code. The complete list is within section 4.1.2.1 of RFC 6749, these are the most commonly encountered:

  • access_denied the user declined your request
  • unsupported_response_type your request's response_type was not code
  • invalid_scope no valid scopes were specified in your request's scope

Requesting an Access Token

Description

Access Tokens are issued as specified in section 4.1.3 of RFC 6749, authentication is performed by including your client_id and client_secret, as issued by Cronofy, within the body of the request.

As with the rest of the API, all requests can be made with a JSON- or forms-encoded request body, though a JSON-encoded request is recommended. You should specify the Content-Type header of your requests as either application/json; charset=utf-8 or application/x-www-form-urlencoded to signal your request body is JSON- or forms-encoded, respectively.

URL format

api.cronofy.com/oauth/token

Example Request

POST /oauth/token HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "grant_type": "authorization_code",
  "code": "{CODE}",
  "redirect_uri": "{REDIRECT_URI}"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
Pragma: no-cache

{
  "token_type": "bearer",
  "access_token": "P531x88i05Ld2yXHIQ7WjiEyqlmOHsgI",
  "expires_in": 3600,
  "refresh_token": "3gBYG1XamYDUEXUyybbummQWEe5YqPmf",
  "scope": "create_event delete_event",
  "account_id": "acc_567236000909002",
  "linking_profile": {
    "provider_name": "google",
    "profile_id": "pro_n23kjnwrw2",
    "profile_name": "example@cronofy.com"
  }
}

Request parameters

client_id required

The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_secret.

client_secret required

The client_secret issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_id.

grant_type required

Must always be authorization_code.

code required

The short-lived, single-use code issued to you when the user authorized your access to their account as part of an Authorization Request.

redirect_uri required

The same HTTP or HTTPS URI you passed when requesting the user's authorization.

Response parameters

token_type

Describes the type of the token as defined in section 7.1 of RFC 6749.

Will always be bearer.

access_token

The new Access Token to use to authenticate when using the API on behalf of the user.

Will always be a 32 character String of ASCII characters.

expires_in

An approximate number of seconds that the new Access Token will be valid for. Will always be a positive integer no greater than 2,147,483,647.

This value may be used to pre-emptively request a new Access Token when this one is expected to have already expired.

However, as being issued new Access Tokens counts for rate limiting but a 401 Unauthorized response for an invalid Access Token does not, it is recommended to use each Access Token you received for as long as possible.

refresh_token

The refresh_token for the granted authorization.

Will always be a 32 character String of ASCII characters.

scope

The Access Token Scope as defined in section 3.3 of RFC 6749.

account_id optional

The ID of the account the credentials relate to.

linking_profile optional

The details of the profile used to authorize access as part of the authorization flow that generated the code.

Will not necessarily be returned as not all authorization flows are guaranteed to involve a profile.

linking_profile.provider_name optional

This specifies the provider of the calendar as a lowercase, ASCII-only String.

Currently one of:

  • apple
  • cronofy
  • exchange
  • google
  • live_connect
  • office365

However, this will be expanded over time and therefore consumers should support any value for this field.

This should be used to help a user distinguish between their profiles as they can have multiple profiles with the same name.

linking_profile.profile_id optional

This specifies the ID of the profile, a profile may consist of many calendars, as an ASCII-only String.

This is used for targetting other API actions toward this profile.

linking_profile.profile_name optional

This specifies the name of the profile as a String.

Error responses

400 Bad Request

Follows the format specified in section 5.2 of RFC 6749, common examples are provided for reference.

Invalid Client

Signifies an unrecognized combination of client_id and client_secret.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_client"
}

This error can be resolved by ensuring your client_id and client_secret are set correctly. Alternatively, you may ask Cronofy to issue you new client credentials but be aware that this will revoke all existing Access and Refresh Tokens.

Invalid Grant

Signifies that the code is unrecognized or has already been used, or that the redirect_uri does not match the one given when requesting the user's authorization.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_grant"
}

If the redirect_uris are identical this error can only be resolved by requesting the user to authorize access again so that you can be issued a new code.


Refreshing an Access Token

Description

Access Tokens are refreshed as specified in section 6 of RFC 6749, authentication is performed by including your client_id and client_secret, as issued by Cronofy, within the body of the request.

As with the rest of the API, all requests can be made with a JSON- or forms-encoded request body, though a JSON-encoded request is recommended. You should specify the Content-Type header of your requests as either application/json; charset=utf-8 or application/x-www-form-urlencoded to signal your request body is JSON- or forms-encoded, respectively.

URL format

api.cronofy.com/oauth/token

Example Request

POST /oauth/token HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "grant_type": "refresh_token",
  "refresh_token": "{REFRESH_TOKEN}"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
Pragma: no-cache

{
  "token_type": "bearer",
  "access_token": "P531x88i05Ld2yXHIQ7WjiEyqlmOHsgI",
  "expires_in": 3600,
  "refresh_token": "{REFRESH_TOKEN}",
  "scope": "create_event delete_event"
}

Request parameters

client_id required

The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_secret.

client_secret required

The client_secret issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_id.

grant_type required

Must always be refresh_token.

refresh_token required

The refresh_token issued to you when the user authorized your access to their account.

Response parameters

token_type

Describes the type of the token as defined in section 7.1 of RFC 6749.

Will always be bearer.

access_token

The new Access Token to use to authenticate when using the API on behalf of the user.

Will always be a 32 character String of ASCII characters.

expires_in

An approximate number of seconds that the new Access Token will be valid for. Will always be a positive integer no greater than 2,147,483,647.

This value may be used to pre-emptively request a new Access Token when this one is expected to have already expired.

However, as being issued new Access Tokens counts for rate limiting but a 401 Unauthorized response for an invalid Access Token does not, it is recommended to use each Access Token you received for as long as possible.

refresh_token

The refresh_token for the granted authorization. Note that this can differ to the one you provided as the refresh_token will be rotated periodically to improve security. Therefore, if the refresh_token in the response differs to the one sent by you in the request, you MUST store the new refresh_token as the old one will no longer be valid.

Failure to store the new refresh_token will mean that the user will have to reauthorize your access once the Access Token expires as you will no longer have a valid refresh_token to request a new one.

Will always be a 32 character String of ASCII characters.

scope

The Access Token Scope as defined in section 3.3 of RFC 6749.

Error responses

400 Bad Request

Follows the format specified in section 5.2 of RFC 6749, common examples are provided for reference.

Invalid Client

Signifies an unrecognized combination of client_id and client_secret.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_client"
}

This error can be resolved by ensuring your client_id and client_secret are set correctly. Alternatively, you may ask Cronofy to issue you new client credentials but be aware that this will revoke all existing Access and Refresh Tokens.

Invalid Grant

Signifies that the refresh_token is unrecognized or revoked.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_grant"
}

This error can only be resolved by requesting the user to authorize access again so that you can be issued a new code and then request a new set of Access and Refresh Tokens.


Revoking Authorization

You may wish to revoke your access on behalf of your users rather than directing them to our site, for example when they unsubscribe from your service or no longer want to use your calendar integration features.

Authorization is revoked as specified in RFC 7009, authentication is performed by including your client_id and client_secret, as issued by Cronofy, within the body of the request.

As with the rest of the API, all requests can be made with a JSON- or forms-encoded request body, though a JSON-encoded request is recommended. You must specify the Content-Type header of your requests as either application/json; charset=utf-8 or application/x-www-form-urlencoded to signal your request body is JSON- or forms-encoded, respectively.

Once revoked, authorization can only be regained by requesting it again.

URL format

api.cronofy.com/oauth/token/revoke

Example Request

POST /oauth/token/revoke HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "token": "{TOKEN}"
}

Example Response

HTTP/1.1 200 OK

Request parameters

client_id required

The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_secret.

client_secret required

The client_secret issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_id.

token required

Either the refresh_token or access_token for the authorization you wish to revoke.

It is recommended that you use the refresh_token as that cannot have expired and therefore be impossible to revoke. RFC 7009 does not provide any provision for a different response when the provided token has already been revoked, has already expired, or does not exist.

Passing either a refresh_token or an access_token will revoke the corresponding refresh_token and all related access_tokens.

Response parameters

This request has no response body.

Error responses

400 Bad Request

Follows the format specified in section 5.2 of RFC 6749, common examples are provided for reference.

Invalid Client

Signifies an unrecognized combination of client_id and client_secret.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_client"
}

This error can be resolved by ensuring your client_id and client_secret are set correctly. Alternatively, you may ask Cronofy to issue you new client credentials but be aware that this will revoke all existing Access and Refresh Tokens.


Enterprise Connect

Description

Enterprise Connect allows you to gain access to the calendars of an entire organization. This eliminates the need to have each calendar user in an organisation individually grant access to their calendar.

An administrator grants you access to their domain and you can use this permission to retrieve access_tokens to calendar accounts on that domain. The access_token can then be used against any endpoint in the Cronofy API.

Enterprise Connect currently supports the following platforms:

  • Exchange
  • Office 365
  • Google

Requesting Authorization for Enterprise Connect

Description

In order to gain access to the calendars of a domain with an Enterprise Connect account it must be authorized by an administrator of that domain.

Example Request

https://app.cronofy.com/enterprise_connect/oauth/authorize
    ?response_type=code
    &client_id={CLIENT_ID}
    &redirect_uri={REDIRECT_URI}
    &scope={SCOPE}
    &delegated_scope={DELEGATED_SCOPE}
    &state={STATE}

Note that the URL for this method differs from that used when authorizing an individual calendar account.

Scopes

The scope of the privileges you want the Enterprise Connect account to be granted. At least one of the following scopes must be requested:

  • service_account/accounts/manage to allow authorization of accounts
  • service_account/accounts/unrestricted_access to allow elevation of access for accounts
  • service_account/resources/manage to allow authorization of resources
  • service_account/resources/unrestricted_access to allow elevation of access for resources

Delegated scopes

The scope of the privileges that can be granted when requesting access to users and resources. At least one of the following scopes must be requested:

Response URL parameters

You will not receive a direct response to your authorization request, instead the administrator will be redirected to the redirect_uri with additional querystring parameters specified.

The responses are fully specified in section 4.1.2 of RFC 6749.

Successful response

code required

A short-lived, single-use code to be used to make an Access Token Request.

Will always be 32 character String of ASCII characters.

state optional

The value you passed for the state within the authorization request.

Error response

error required

A single ASCII error code. The complete list is within section 4.1.2.1 of RFC 6749, these are the most commonly encountered:

  • access_denied the administrator declined your request
  • unsupported_response_type your request's response_type was not code
  • invalid_scope no valid scopes were specified in your request's scope

Requesting an Access Token for Enterprise Connect

Description

Access Tokens are issued as specified in section 4.1.3 of RFC 6749, authentication is performed by including your client_id and client_secret, as issued by Cronofy, within the body of the request.

As with the rest of the API, all requests can be made with a JSON- or forms-encoded request body, though a JSON-encoded request is recommended. You should specify the Content-Type header of your requests as either application/json; charset=utf-8 or application/x-www-form-urlencoded to signal your request body is JSON- or forms-encoded, respectively.

URL format

api.cronofy.com/oauth/token

Example Request

POST /oauth/token HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "grant_type": "authorization_code",
  "code": "{CODE}",
  "redirect_uri": "{REDIRECT_URI}"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
Pragma: no-cache

{
  "token_type": "bearer",
  "access_token": "P531x88i05Ld2yXHIQ7WjiEyqlmOHsgI",
  "expires_in": 1800,
  "refresh_token": "3gBYG1XamYDUEXUyybbummQWEe5YqPmf",
  "scope": "service_account/accounts/manage",
  "service_account_id": "ser_529716002600402"
}

Request parameters

client_id required

The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_secret.

client_secret required

The client_secret issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_id.

grant_type required

Must always be authorization_code.

code required

The short-lived, single-use code issued to you when the administrator authorized your access to their Enterprise Connect account as part of an Enterprise Connect Authorization Request.

redirect_uri required

The same HTTP or HTTPS URI you passed when requesting the administrator's authorization.

Response parameters

token_type

Describes the type of the token as defined in section 7.1 of RFC 6749.

Will always be bearer.

access_token

The new Access Token to use to authenticate when using the API on behalf of the Enterprise Connect account.

Will always be a 32 character String of ASCII characters.

expires_in

An approximate number of seconds that the new Access Token will be valid for. Will always be a positive integer no greater than 2,147,483,647.

This value may be used to pre-emptively request a new Access Token when this one is expected to have already expired.

However, as being issued new Access Tokens counts for rate limiting but a 401 Unauthorized response for an invalid Access Token does not, it is recommended to use each Access Token you received for as long as possible.

refresh_token

The refresh_token for the granted authorization.

Will always be a 32 character String of ASCII characters.

scope

The Access Token Scope as defined in section 3.3 of RFC 6749.

service_account_id

The ID of the Enterprise Connect account the credentials relate to.

Error responses

400 Bad Request

Follows the format specified in section 5.2 of RFC 6749, common examples are provided for reference.

Invalid Client

Signifies an unrecognized combination of client_id and client_secret.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_client"
}

This error can be resolved by ensuring your client_id and client_secret are set correctly. Alternatively, you may ask Cronofy to issue you new client credentials but be aware that this will revoke all existing Access and Refresh Tokens.

Invalid Grant

Signifies that the code is unrecognized or has already been used, or that the redirect_uri does not match the one given when requesting the administrator's authorization.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_grant"
}

If the redirect_uris are identical this error can only be resolved by requesting the administrator to authorize access again so that you can be issued a new code.


Refreshing an Access Token for Enterprise Connect

Description

Access Tokens are refreshed as specified in section 6 of RFC 6749, authentication is performed by including your client_id and client_secret, as issued by Cronofy, within the body of the request.

As with the rest of the API, all requests can be made with a JSON- or forms-encoded request body, though a JSON-encoded request is recommended. You should specify the Content-Type header of your requests as either application/json; charset=utf-8 or application/x-www-form-urlencoded to signal your request body is JSON- or forms-encoded, respectively.

Due to the more sensitive nature of Enterprise Connect accounts, the access_tokens issued for them have a shorter lifetime than standard access_tokens.

URL format

api.cronofy.com/oauth/token

Example Request

POST /oauth/token HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "grant_type": "refresh_token",
  "refresh_token": "{REFRESH_TOKEN}"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
Pragma: no-cache

{
  "token_type": "bearer",
  "access_token": "P531x88i05Ld2yXHIQ7WjiEyqlmOHsgI",
  "expires_in": 1800,
  "refresh_token": "{REFRESH_TOKEN}",
  "scope": "create_event delete_event"
}

Request parameters

client_id required

The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_secret.

client_secret required

The client_secret issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your client_id.

grant_type required

Must always be refresh_token.

refresh_token required

The refresh_token issued to you when the user authorized your access to their account.

Response parameters

token_type

Describes the type of the token as defined in section 7.1 of RFC 6749.

Will always be bearer.

access_token

The new Access Token to use to authenticate when using the API on behalf of the user.

Will always be a 32 character String of ASCII characters.

expires_in

An approximate number of seconds that the new Access Token will be valid for. Will always be a positive integer no greater than 2,147,483,647.

This value may be used to pre-emptively request a new Access Token when this one is expected to have already expired.

However, as being issued new Access Tokens counts for rate limiting but a 401 Unauthorized response for an invalid Access Token does not, it is recommended to use each Access Token you received for as long as possible.

refresh_token

The refresh_token for the granted authorization. Note that this can differ to the one you provided as the refresh_token will be rotated periodically to improve security. Therefore, if the refresh_token in the response differs to the one sent by you in the request, you MUST store the new refresh_token as the old one will no longer be valid.

Failure to store the new refresh_token will mean that the user will have to reauthorize your access once the Access Token expires as you will no longer have a valid refresh_token to request a new one.

Will always be a 32 character String of ASCII characters.

scope

The Access Token Scope as defined in section 3.3 of RFC 6749.

Error responses

400 Bad Request

Follows the format specified in section 5.2 of RFC 6749, common examples are provided for reference.

Invalid Client

Signifies an unrecognized combination of client_id and client_secret.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_client"
}

This error can be resolved by ensuring your client_id and client_secret are set correctly. Alternatively, you may ask Cronofy to issue you new client credentials but be aware that this will revoke all existing Access and Refresh Tokens.

Invalid Grant

Signifies that the code is unrecognized or has already been used, or that the redirect_uri does not match the one given when requesting the administrator's authorization.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_grant"
}

If the redirect_uris are identical this error can only be resolved by requesting the administrator to authorize access again so that you can be issued a new code.


Requesting Delegated Access

Description

When authenticated for an Enterprise Connect account, a short lived code can be obtained for an account or resource that can then be exchanged for an access_token and refresh_token for the account or resource.

This can be thought of as being similar to the standard OAuth authorization flow, but it happens without any direct user involvement.

The steps are:

URL format

api.cronofy.com/v1/service_account_authorizations

Example request

POST /v1/service_account_authorizations HTTP/1.1
HOST: api.cronofy.com
Content-Type: application/json; charset=utf-8
{
    "email" : "{EMAIL_OF_DELEGATED_ACCOUNT}",
    "callback_url": "{CALLBACK_URL}",
    "scope" : "{SCOPES}",
    "state": "{STATE}"
}

Example Response

HTTP/1.1 202 Accepted

You will not receive a direct response to your Authorization Request, instead the callback_url will receive a request in the future indicating success or failure.

Request parameters

email

The email address of the account or resource to receive delegated access to.

callback_url

The URL to callback with the result of the delegated access request.

See Callback examples for examples of the types of request the callback_url will receive.

scope

The scope of the privileges you want the eventual access_token to grant.

These must have previously been granted via the delegated_scope parameter of an Enterprise Connect authorization request.

state optional

A value that will be returned to you unaltered along with the authorization request decision.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required email parameter, you would receive a response like:

{
  "errors": {
    "email": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.

Example callback responses

Successful authorization example


POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8

{
  "authorization": {
    "code":  "{CODE}",
    "state": "{STATE}"
  }
}

The authorization.code returned can be redeemed for an access_token and refresh_token as if the code had been returned in response to a regular Authorization Request.

Note that the callback_url must be passed to the subsequent Access Token Request and may be passed as a parameter named callback_url (for consistency in this flow) or redirect_uri (if you want to share code for redeeming tokens between the different flows).

Failed authorization example

{
  "authorization": {
    "error": "access_denied",
    "error_key": "unknown_email",
    "error_description": "Unknown user or email"
  }
}

Request parameters

authorization.error

The type of error, always access_denied to indicate the authorization request failed.

authorization.error_key

The specific reason for the authorization failure. Currently one of:

  • unknown_email no account or resource was found with the given email and so authorization should not be reattempted

Listing Resources (Rooms and Equipment)

Description

The resources (rooms and equipment) associated with an Enterprise Connect account can be listed via the resources endpoint.

This requires the Enterprise Connect authentication to have the service_account/resources/manage scope granted.

URL format

api.cronofy.com/v1/resouces

Example request

GET /v1/resources HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

Example Response

HTTP/1.1 200 OK

{
  "resources": [
    {
      "email": "board-room-london@example.com",
      "name": "Board room (London)"
    },
    {
      "email": "board-room-madrid@example.com",
      "name": "Board room (Madrid)"
    },
    {
      "email": "3dprinter@example.com",
      "name": "3D Printer"
    },
    {
      "email": "vr-headset@example.com",
      "name": "Oculus Rift"
    }
  ]
}

Response parameters

resources.email

The email address for the resource.

May be used to obtain access tokens for the resource calendar via Requesting Delegated Access.

resources.name

The name defined for the resource by the Enterprise Connect account.

Exchange and Office 365 users will need to ensure that any resources are added to a room list in order for these resources to be viewable for details on how to configure this for Office 365 see: enabling room list distribution groups.


List Calendars

Description

Returns a list of all the authenticated user's calendars.

URL format

api.cronofy.com/v1/calendars

Example Request

GET /v1/calendars HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "calendars": [
    {
      "provider_name": "google",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
      "calendar_name": "Home",
      "calendar_readonly": false,
      "calendar_deleted": false,
      "calendar_primary": true
    },
    {
      "provider_name": "google",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_n23kjnwrw2_n1k323nkj23",
      "calendar_name": "Work",
      "calendar_readonly": true,
      "calendar_deleted": true,
      "calendar_primary": false
    },
    {
      "provider_name": "apple",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_n23kjnwrw2_3nkj23wejk1",
      "calendar_name": "Bank Holidays",
      "calendar_readonly": true,
      "calendar_deleted": false,
      "calendar_primary": false
    }
  ]
}

Response parameters

calendars.provider_name

This specifies the provider of the calendar as a lowercase, ASCII-only String.

Currently one of:

  • apple
  • cronofy
  • exchange
  • google
  • live_connect
  • office365

However, this will be expanded over time and therefore consumers should support any value for this field.

This should be used to help a user distinguish between their calendars as they can have multiple calendars with the same name.

calendars.profile_id

This specifies the ID of the profile, a profile may consist of many calendars, as an ASCII-only String.

This is used for targetting other API actions toward this profile.

calendars.profile_name

This specifies the name of the profile that the calendar is part of as a String.

This should be used to help a user distinguish between their calendars as they can have multiple calendars with the same name.

calendars.calendar_id

This specifies the ID of the calendar as an ASCII-only String.

This is used for targetting other API actions toward this calendar.

calendars.calendar_name

This specifies the name of the calendar as a String.

This should be used to help a user distinguish between their calendars as they can have multiple calendars within the same profile.

calendars.calendar_readonly

This specifies whether the calendar is readonly as a Boolean.

Calendars where calendar_readonly is true will refuse requests to create, update, or delete events.

calendars.calendar_deleted

This specifies whether the calendar has been deleted as a Boolean.

Calendars where calendar_deleted is true will refuse requests to create, update, or delete events.

calendars.calendar_primary

This specifies whether the calendar is the primary calendar for its profile as a Boolean.

Current support by provider:

  • Apple has no concept of primary calendars
  • Exchange has a primary calendar which cannot change
  • Google has a primary calendar which cannot change
  • Office 365 has a primary calendar which cannot change
  • Outlook.com has a primary calendar which can change

Create Calendar

Description

Creates a calendar within a user's profile.

In order for this to be possible, you must request the create_calendar scope when requesting authorization to access the user's calendars.

URL format

api.cronofy.com/v1/calendars

Example Request

POST /v1/calendars HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "profile_id": "pro_n23kjnwrw2",
  "name": "New Calendar"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "calendar": {
    "provider_name": "google",
    "profile_id": "pro_n23kjnwrw2",
    "profile_name": "example@cronofy.com",
    "calendar_id": "cal_n23kjnwrw2_sakdnawerd3",
    "calendar_name": "New Calendar",
    "calendar_readonly": false,
    "calendar_deleted": false
  }
}

Request parameters

profile_id required

The profile_id of the profile you wish the calendar to be added to. This ID should have been discovered by making a list calendars request.

name required

The String to use as the name of the calendar.

Response parameters

calendar.provider_name

This specifies the provider of the calendar as a lowercase, ASCII-only String.

Currently one of:

  • apple
  • cronofy
  • exchange
  • google
  • live_connect
  • office365

However, this will be expanded over time and therefore consumers should support any value for this field.

This should be used to help a user distinguish between their calendars as they can have multiple calendars with the same name.

calendar.profile_id

This specifies the ID of the profile, a profile may consist of many calendars, as an ASCII-only String.

This is used for targetting other API actions toward this profile.

calendar.profile_name

This specifies the name of the profile that the calendar is part of as a String.

This should be used to help a user distinguish between their calendars as they can have multiple calendars with the same name.

calendar.calendar_id

This specifies the ID of the calendar as an ASCII-only String.

This is used for targetting other API actions toward this calendar.

calendar.calendar_name

This specifies the name of the calendar as a String.

This should be used to help a user distinguish between their calendars as they can have multiple calendars within the same profile.

calendar.calendar_readonly

This specifies whether the calendar is readonly as a Boolean.

Calendars where calendar_readonly is true will refuse requests to create, update, or delete events.

calendar.calendar_deleted

This specifies whether the calendar has been deleted as a Boolean.

Calendars where calendar_deleted is true will refuse requests to create, update, or delete events.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

403 Forbidden

The request was refused as the provided authorization credentials were recognized but does not grant the create_calendar scope.

You will need to make an additional authorization request including the create_calendar scope before retrying the request.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required name field, you would receive a response like:

{
  "errors": {
    "name": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.

423 Locked

Unlike most of our API calls, calendar creation needs to be proxied through to the underlying provider. Therefore, these requests are generally slower and more liable to failure due to more parties being involved.

Also, it is worth highlighting that some providers (only exchange at this point in time) disallow calendars with duplicate names. If you provide a duplicate name, you will receive a 422 Unprocessable response with a body like:

{
  "errors": {
    "name": [
      {
        "key": "errors.duplicate_calendar_name",
        "description": "A calendar with this name already exists and the provider does not allow duplicates"
      }
    ]
  }
}

As detailed in the documentation of this kind of response, the key field is intended for programmatic use and the description field is a human-readable equivalent.


Availability

Description

Inspects calendars to determine the common availablity for people within the specified periods of time.

URL format

api.cronofy.com/v1/availability

Example Request

POST /v1/availability HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_567236000909002",
          "calendar_ids": ["cal_n23kjnwrw2_jsdfjksn234"]
        },
        {
          "sub": "acc_678347111010113",
          "available_periods": [
            {
              "start": "2017-03-28T09:00:00Z",
              "end": "2017-03-28T12:00:00Z"
            },
            {
              "start": "2017-03-29T10:00:00Z",
              "end": "2017-03-29T20:00:00Z"
            }
          ]
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2017-03-28T09:00:00Z",
      "end": "2017-03-28T18:00:00Z"
    },
    {
      "start": "2017-03-29T09:00:00Z",
      "end": "2017-03-29T18:00:00Z"
    }
  ]
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "available_periods": [
    {
      "start": "2017-03-28T09:00:00Z",
      "end": "2017-03-28T11:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    },
    {
      "start": "2017-03-29T11:00:00Z",
      "end": "2017-03-29T17:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    },
  ]
}

Request parameters

participants required

An array of the groups of participants whose availability should be taken into account.

At least one group must be specified, a maximum of 10 accounts may be specified over a combination of groups.

participants.members required

An array of participants that should have their availability taken into account as part of this group.

At least one participant must be specified and you must have been granted the read_free_busy scope for each participant involved in the availability request.

Note that the read_events scope implicitly includes this scope as it allows access to a higher level of information than free-busy so you do not have to have both.

participants.members.sub required

The internal Cronofy ID for the account, as an ASCII-only String.

This can be retrieved by calling the UserInfo endpoint with a valid access_token

participants.members.available_periods optional

An array of 1 to 10 available periods within which the member is available. If omitted it is assumed the member is available whenever they do not have a "busy" event in their calendar.

participants.members.available_periods.start required

Thestart of an available period as a Time.

It must represent a point in time up to 35 days into the future.

participants.members.available_periods.end required

Theend of an available period as a Time.

Must be between 1 minute and 24 hours after the correspondingstart.

participants.members.calendar_ids optional

Restricts the events contributing towards the members availability to those within the set of specified calendar_ids.

participants.required required

Either a String of all to specify that all members of the group need to be available for a period to be viable, or an Integer of 1 to specify that at least one member of the group must be available.

required_duration required

An object describing the minimum period that the participant groups must be satisfied for a period to be deemed as available.

required_duration.minutes required

An Integer specifying the number of minutes that an available period must last to be considered viable.

Must be a value of at least 1.

available_periods required

An array of 1 to 10 available periods within which suitable matches may be found.

available_periods.start required

Thestart of an available period as a Time.

It must represent a point in time up to 35 days into the future.

available_periods.end required

Theend of an available period as a Time.

Must be between 1 minute and 24 hours after the correspondingstart.

Response parameters

available_periods

An array of available periods that match the criteria specified in the request.

A maximum of 10 results will be returned with preference being towards the soonest matches.

available_periods.start

Thestart of an available period as a Time.

available_periods.end

Theend of an available period as a Time.

available_periods.participants

An array of participants that are available for the given period.

available_periods.participants.sub

The internal Cronofy ID for the account, as an ASCII-only String.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

Note that whilst many accounts can be part of the availability request that authentication is performed via theaccess_token for only one of them.

When an OAuthrefresh_token is available then it should be used to request a replacementauth_token before the request is retried.

402 Payment Required

The request was refused as your plan does not include the required feature.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required required_duration parameter, you would receive a response like:

{
  "errors": {
    "required_duration": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.


Free Busy

Description

Returns a list of free-busy information across all of a users calendars.

By default, the events you are managing on behalf of the account are excluded from the query results.

The returned free-busy periods will start before the given to Date and will end on or after the given from Date.

Note that the events you manage are not subject to the default from and to date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time.

Example Request

The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request's path for clarity.

GET /v1/free_busy?from={FROM_DATE}&to={TO_DATE}
    &tzid={TZID} HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "pages": {
    "current": 1,
    "total": 2,
    "next_page": "https://api.cronofy.com/v1/free_busy/pages/caa2dca822d5d74d98104489"
  },
  "free_busy": [
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "start": "2014-09-06T08:00:00Z",
      "end": "2014-09-08T08:30:00Z",
      "free_busy_status": "busy",
    },
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "start": "2014-09-10",
      "end": "2014-09-11",
      "free_busy_status": "free",
    }
  ]
}

Request parameters

from optional

The minimum Date from which to return free-busy information.

If not provided, defaults to the minimum value of 42 days in the past.

to optional

The Date to return free-busy information up until.

If not provided, defaults to the maximum value of 201 days in the future.

Note that the results will not include events occurring on this date.

tzid required

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

It is recommended that you use the same tzid for all requests made for an individual user in order to ensure all their events are returned to you.

include_managed optional

A Boolean specifying whether events that you are managing for the account should be included or excluded from the results.

If not provided, only non-managed events are returned.

Note that the events you manage are not subject to the default from and to date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time.

calendar_ids[] optional

Restricts the returned free-busy information to that within the set of specified calendar_ids.

The calendar_ids[] parameter can be specified multiple times within the query string to include free-busy information from multiple calendars:

calendar_ids[]=cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw&calendar_ids[]=cal_U@y23bStTFV7AAAB_iWTeH8WOCDOIW@us5gRzww

The possible calendar_ids can be discovered through the list calendars endpoint.

If no calendars are specified, the default behaviour is to return events from all of the user's calendars.

localized_times optional

A Boolean specifying whether the free-busy periods should have their start and end times returned with any available localization information.

If not provided the start and end times will be returned as simple Time values.

Response parameters

pages.current

An Integer specifying which page of the result set the current request is for.

pages.total

An Integer specifying the total number of pages in the result set.

pages.next_page optional

When present, a String specifying the URL for the next page of results.

The next page of results can be retrieved by issuing a GET request to this URL and you will receive a response in the same format as a regular free-busy request.

All pages within a result set are generated at the same time to avoid any mid-paging modification issues. They are then temporarily cached for retrieval as individual pages.

free_busy.calendar_id

This specifies the ID of the calendar as an ASCII-only String.

free_busy.start

When localized_times is not specified or is false, the Time or Date representing when the free-busy period starts.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date representing when the free-busy period starts. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
free_busy.end

When localized_times is not specified or is false, the Time or Date by which the free-busy period ends.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the free-busy period ends. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
free_busy.free_busy_status

A String defining the free-busy status of the block.

One of:

  • tentative
    the user is probably busy for this period of time
  • busy
    the user is busy for this period of time
  • free
    the user is free for this period of time
  • unknown
    the status of the period is unknown

unknown is not expected to be used but is included and documented so there is a documented response for periods we may not know how to categorize.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

403 Forbidden

The request was refused as the provided authorization credentials were recognized but does not grant the read_free_busy scope which was required for the request.

You will need to make an additional authorization request including the read_free_busy scope before retrying the request.

Note that the read_events scope implicitly includes this scope as it allows access to a higher level of information than free-busy so you do not have to request both.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required tzid parameter, you would receive a response like:

{
  "errors": {
    "tzid": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.


Read Events

Description

Returns a list of events across all of a users calendars.

By default, the events you are managing on behalf of the account are excluded from the query results.

The returned events will start before the given to Date and will end on or after the given from Date.

Note that the events you manage are not subject to the default from and to date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time.

Example Request

The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request's path for clarity.

GET /v1/events?from={FROM_DATE}&to={TO_DATE}
    &tzid={TZID} HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "pages": {
    "current": 1,
    "total": 2,
    "next_page": "https://api.cronofy.com/v1/events/pages/08a07b034306679e"
  },
  "events": [
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "event_uid": "evt_external_54008b1a4a41730f8d5c6037",
      "summary": "Company Retreat",
      "description": "",
      "start": "2014-09-06",
      "end": "2014-09-08",
      "deleted": false,
      "created": "2014-09-01T08:00:01Z",
      "updated": "2014-09-01T09:24:16Z",
      "location": {
        "description": "Beach"
      },
      "participation_status": "needs_action",
      "attendees": [
        {
          "email": "example@cronofy.com",
          "display_name": "Example Person",
          "status": "needs_action"
        }
      ],
      "organizer": {
        "email": "example@cronofy.com",
        "display_name": "Example Person"
      },
      "transparency": "opaque",
      "status": "confirmed",
      "categories": [],
      "recurring": false,
      "options": {
        "delete": true,
        "update": true,
        "change_participation_status": true
      }
    }
  ]
}

Request parameters

from optional

The minimum Date from which to return events, when provided must be greater than or equal to 42 days in the past.

If not provided, defaults to the minimum value of 42 days in the past.

to optional

The Date to return events up until, when provided must be less than or equal to 201 days in the future.

If not provided, defaults to the maximum value of 201 days in the future.

Note that the results will not include events occurring on this date.

tzid required

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

It is recommended that you use the same tzid for all requests made for an individual user in order to ensure all their events are returned to you.

include_deleted optional

A Boolean specifying whether events that have been deleted should included or excluded from the results.

If not provided, only non-deleted events are returned.

include_moved optional

A Boolean specifying whether events that have ever existed within the given window should be included or excluded from the results.

If not provided, only events that are currently within the search period are returned.

last_modified optional

The Time that events must be modified on or after in order to be returned.

If not provided, all events are returned regardless of when they were last modified.

include_managed optional

A Boolean specifying whether events that you are managing for the account should be included or excluded from the results.

If not provided, only non-managed events are returned.

Note that the events you manage are not subject to the default from and to date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time.

only_managed optional

A Boolean specifying whether only events that you are managing for the account should be included in the results.

Note that the events you manage are not subject to the default from and to date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time.

calendar_ids[] optional

Restricts the returned events to those within the set of specified calendar_ids.

The calendar_ids[] parameter can be specified multiple times within the query string to include events from multiple calendars:

calendar_ids[]=cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw&calendar_ids[]=cal_U@y23bStTFV7AAAB_iWTeH8WOCDOIW@us5gRzww

The possible calendar_ids can be discovered through the list calendars endpoint.

If no calendars are specified, the default behaviour is to return events from all of the user's calendars.

localized_times optional

A Boolean specifying whether the events should have their start and end times returned with any available localization information.

If not provided the start and end times will be returned as simple Time values.

include_geo optional

A Boolean specifying whether the events should have their location.lat and location.long returned where available.

Verified applications must have geo-location included in their plan or the API call will result in a 402 error.

Response parameters

pages.current

An Integer specifying which page of the result set the current request is for.

pages.total

An Integer specifying the total number of pages in the result set.

pages.next_page optional

When present, a String specifying the URL for the next page of results.

The next page of results can be retrieved by issuing a GET request to this URL and you will receive a response in the same format as a regular read events request.

All pages within a result set are generated at the same time to avoid any mid-paging modification issues. They are then temporarily cached for retrieval as individual pages.

events.calendar_id

This specifies the ID of the calendar as an ASCII-only String.

events.event_uid

This uniquely identifies the event as an ASCII-only String.

events.summary

The String value of the summary, sometimes referred to as the name, of the event.

events.description

The String value of the description, sometimes referred to as the notes, of the event.

events.start

When localized_times is not specified or is false, the Time or Date representing when the event starts.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date representing when the event starts. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
events.end

When localized_times is not specified or is false, the Time or Date by which the event ends.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the event ends. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
events.deleted

This specifies whether the event has been deleted as a Boolean.

events.created

The Time the event was created.

events.updated

The Time the event was last updated.

events.location.description optional

The String describing the event's location.

events.location.lat optional

The String representing the event's latitude.

events.location.long optional

The String representing the event's longitude.

events.event_id optional

When the event is one you are managing for the account, the event_id you specified when creating the event will be returned to allow you to reconcile it against your system.

events.participation_status

A String representing the participation status of the account with regard to the event.

One of:

  • needs_action
    the event needs action by the account, usually they have been sent an invite but are yet to respond
  • accepted
    they have accepted an invitation to the event
  • declined
    they have declined an invitiation to the event
  • tentative
    they have tentatively accepted an invitation to the event
  • unknown
    their participation status for the event is unknown

This is intended to help discern the status of the event for the account without having to understand which of the attendees entries relates to them. It will also be populated when there are no attendees as this is inferred to be a personal entry.

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

events.attendees.email

The email address associated with the attendee as a String.

events.attendees.display_name

A human-friendly name associated with the attendee as a String, may be null.

events.attendees.status

A String representing the participation status of the attendee with regard to the event.

One of:

  • needs_action
    the event needs action by the attendee, usually they have been sent an invite but are yet to respond
  • accepted
    they have accepted an invitation to the event
  • declined
    they have declined an invitiation to the event
  • tentative
    they have tentatively accepted an invitation to the event
  • unknown
    their participation status for the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for attendees we may not know how to categorize.

events.organizer.email

The email address of the organizer as a String.

events.organizer.display_name

A human-friendly name of the organizer as a String, may be null.

events.transparency

A String defining whether an event is transparent or not to free-busy searches.

One of:

  • opaque
    the account should appear as busy for the duration of the event
  • transparent
    the account should not appear as busy for the duration of the event
  • unknown
    their transparency of the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

events.status

A String defining the overall status of the event.

One of:

  • tentative
    the event is probably going to occur
  • confirmed
    the event is going to occur
  • cancelled
    the event is no longer going to occur
  • unknown
    the status of the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

events.categories

An array of Strings exposing the categories assigned to the event.

Each category is a free-text String. For the underlying providers that do not support the concept of categories, this will always be an empty array.

events.recurring

A Boolean specifying whether this is a recurring event.

events.options.delete

A Boolean specifying whether permission exists to delete this event.

events.options.update

A Boolean specifying whether permission exists to update this event.

events.options.change_participation_status

A Boolean specifying whether permission exists to change the user's participation status with regard to this event.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

403 Forbidden

The request was refused as the provided authorization credentials were recognized but does not grant the read_events scope which was required for the request.

You will need to make an additional authorization request including the read_events scope before retrying the request.

Note that if you only want to read the events you are managing, you do not need this scope so long as you pass a only_managed parameter of true.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required tzid parameter, you would receive a response like:

{
  "errors": {
    "tzid": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.


Create or Update Event

Description

Creates or updates an event within a user's calendar.

URL format

api.cronofy.com/v1/calendars/{calendar_id}/events

Example Request

POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2014-08-05T15:30:00Z",
  "end": "2014-08-05T17:00:00Z",
  "location": {
    "description": "Board room"
  }
}

Example Response

HTTP/1.1 202 Accepted

Request parameters

calendar_id required

The calendar_id of the calendar you wish the event to be added to. This ID should have been discovered by making a list calendars request and must not have a calendar_readonly or calendar_deleted value that is true.

event_id required

The String that uniquely identifies the event. The first request made for a calendar_id and event_id combination will create an entry in the calendar and all subsequent requests will update the details of the event.

Usually this will be your own internal ID for the event, encoded as a String.

summary required

The String to use as the summary, sometimes referred to as the name, of the event.

description required

The String to use as the description, sometimes referred to as the notes, of the event.

tzid optional

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the default tzid to use for the start and end times of the event if they do not specify their own.

If not provided, Etc/UTC is used by default.

Please note the caveats on time zone usage by provider.

start required

The start time can be provided as a simple Time or Date string or an object with two attributes, time and tzid:

{
  "time": "2014-08-05T17:00:00Z",
  "tzid": "Europe/Paris"
}

The time attribute specifies the Time or Date to use as the start of the event. Regardless of the tzid used, this value is always provided in UTC time so as to not be ambiguous.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the tzid to use for the start time of the event.

If not provided, the tzid attribute of the event is used if specified, otherwise Etc/UTC is used.

Please note the caveats on time zone usage by provider.

When start is specified as a Time, end must be specified as a Time. Likewise, when start is specified as a Date, end must be specified as a Date.

end required

The end time can be provided as a simple Time or Date string or an object with two attributes, time and tzid:

{
  "time": "2014-08-05T17:00:00Z",
  "tzid": "Europe/Paris"
}

The time attribute specifies the Time or Date to use as the end time of the event. Regardless of the tzid used, this value is always provided in UTC time so as to not be ambiguous. Also, it must be later in time than the start of the event.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the tzid to use for the end time of the event.

If not provided, the tzid attribute of the event is used if specified, otherwise Etc/UTC is used.

Please note the caveats on time zone usage by provider.

When start is specified as a Time, end must be specified as a Time. Likewise, when start is specified as a Date, end must be specified as a Date.

Also note that end is exclusive, for Time-based events this makes no noticeable difference, but for Date-based events this can be confusing. It may help to think of the end as the point in time by which the event will have ended. When based on time the event an event with an end of 11:30 is actually expected to end at 11:29.99999 so it would not overlap a following event starting at 11:30. When working with dates the same logic applies so an all day event you wish to cover March 17th would start on March 17th but end before March 18th.

location.description optional

The String describing the event's location.

url optional

A String value which must be parseable as a URI as defined as defined in RFC 1738 and RFC 2111.

Omitting the value will leave the URL unchanged. Setting the value to null will remove the URL if supported by the provider.

Support for event URLs is currently limited to Apple and Google. Please note there is an issue with Google whereby URLs are not removable once they are provided.

transparency optional

A String value representing the transparency of the event.

Either:

  • opaque
    the account should appear as busy for the duration of the event
  • transparent
    the account should not appear as busy for the duration of the event

If not provided, transparent is used for all-day events, and opaque for Time-based events.

reminders optional

You can provide an array of up to 5 reminders for an event. They should be provided in order of priority for your application, not time order. This is because the providers support a varying number of reminders and we will set as many as they allow, in the order you provide them.

Number of reminders supported per provider:

  • Apple 5 reminders, note that icloud.com will only display two
  • Exchange 1 reminder
  • Google 5 reminders
  • Office 365 1 reminder
  • Outlook.com 1 reminder

For example, if you provide 3 reminders and the provider only supports one, we will use the first one you specify, not the earliest or the latest one.

As a concrete example, whilst we advise erring on the side of setting less reminders rather than more, it is easy to imagine that 3 reminders may be useful for an appointment:

  • 30 minutes before event start - get to the appointment
  • 24 hours before event start - remember about the appointment
  • At event start - the appointment should have started

In a request this would look like:

POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2014-08-05T15:30:00Z",
  "end": "2014-08-05T17:00:00Z",
  "location": {
    "description": "Board room"
  },
  "reminders": [
    { "minutes": 30 },
    { "minutes": 1440 },
    { "minutes": 0 }
  ]
}
reminders.minutes required

An Integer specifying the number of minutes before the start of the event that the reminder should occur.

Must be between 0 and 40,320, from the time the event starts to 4 weeks before the event starts, inclusive.

Caveats

Time Zone Information

Time zone information can be provided with your events so we can insert events with localized times into your users calendars when the underlying provider allows.

Current time zone support by provider:

  • Apple separate time zones for start and end
  • Exchange uses start time zone for both start and end
  • Google uses start time zone for both start and end
  • Office 365 uses start time zone for both start and end
  • Outlook.com uses start time zone for both start and end

Please note that even we when can push a separate time zone for start and end, some clients (for example OSX Calendar.app) will display them as if they are both for the start time zone.

Response parameters

This request has no response body.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

403 Forbidden

The request was refused as the provided authorization credentials were recognized but does not grant the create_event scope.

You will need to make an additional authorization request including the create_event scope before retrying the request.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required event_id field, you would receive a response like:

{
  "errors": {
    "event_id": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.


Delete Event

Description

Deletes an event from a user's calendar.

URL format

api.cronofy.com/v1/calendars/{calendar_id}/events

Example Request

DELETE /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg"
}

Example Response

HTTP/1.1 202 Accepted

Request parameters

calendar_id required

The calendar_id of the calendar you wish the event to be removed from. This ID should have been discovered by making a list calendars request and must not have a calendar_readonly value that is true.

event_id required

The String that uniquely identifies the event. The combination of calendar_id and event_id combination will be used to delete the event.

Usually this will be your own internal ID for the event, encoded as a String.

Response parameters

This request has no response body.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

403 Forbidden

The request was refused as the provided authorization credentials were recognized but does not grant the delete_event scope.

You will need to make an additional authorization request including the delete_event scope before retrying the request.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required event_id field, you would receive a response like:

{
  "errors": {
    "event_id": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.


Bulk Delete Events

Description

Delete events that you are managing from the user's calendars in bulk.

URL format

api.cronofy.com/v1/events

Example Requests

Delete all events from all calendars
DELETE /v1/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "delete_all": true
}
Delete all events from specific calendars
DELETE /v1/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "calendar_ids" : [ "cal_n23kjnwrw2_sakdnawerd3" ]
}

Example Response

HTTP/1.1 202 Accepted

Request parameters

delete_all optional

A Boolean specifying whether all events you are managing for the user should be deleted. When specified must be true.

calendar_ids optional

An Array specifying the calendars from which to delete all events you are managing for the user. When provided at least one calendar must be specified.

Response Errors

Only one of delete_all or calendar_ids must be provided in the body, if both are set this is considered an error.


Participation Status

Description

Changes the status of a user's participation in an event

In order for this to be possible, you must request the change_participation_status scope when requesting authorization to access the user's calendars.

URL format

api.cronofy.com/v1/calendars/{calendar_id}/events/{event_uid}/participation_status

Example Request

POST /v1/calendars/{calendar_id}/events/{event_uid}/participation_status HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
    "status": "accepted"
}

Example Response

HTTP/1.1 202 Accepted

Request parameters

calendar_id required

The calendar_id of the calendar that contains the event for which you'd like to update the participation status. This ID can be retrieved using a list calendars request

This calendar must not have a calendar_readonly value that is true.

event_uid required

The String that uniquely identifies the event. This ID can be retrieved using the read events request.

This event must be have its options.change_participation_status flag set to true.

status required

A String representing the participation status you'd like to set. Acceptable values are:

  • accepted - to accept the invite
  • tentative - to tentatively accept the invite
  • declined - to decline the invite

Push Notifications

Description

Push notifications provide a mechanism to lazily retrieve information about an account in order to avoid the need for API clients to create polling infrastructure.

Rather than having to frequently check for changes, instead we inform you when changes have occurred so that you can retrieve them.

This enables you to keep your data as fresh as possible whilst using minimal computing resources.

Push notifications are available for all calendar providers, not just those that support them natively.

Push Notification Request

Example Request

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8

{
  "notification": {
    "type": "change",
    "changes_since": "2014-09-01T09:24:16Z"
  },
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {
      "calendar_ids": [ "cal_n23kjnwrw2_sakdnawerd3" ],
      "only_managed": false
    }
  }
}

Once a push notification channel has been created the callback URL specified will receive push notifications for changes to the user's account and calendars.

These will come in the form of POST requests with a Content-Type of application/json; charset=utf-8.

Request parameters

notification.type

The type of change this notification is for.

There are currently three types of notification but your code should be tolerant of others, by ignoring them, so if more are introduced in future your integration will not fail.

Current types:

  • verification sent after a channel is created to test that the specified callback URL is valid
  • change signifies that a change has occurred to the user's events so you should make a request to fetch those changes
  • profile_disconnected signifies that one or more of the user's calendar profiles has become disconnected and the user will need to reauthorize the affected calendar account. Profile Information gives current connection status for all profiles associated with a user.
notification.changes_since

The Time that the last change was seen.

This is only sent as part of a change notification and may be used as the last_modified parameter for a subsequent Read Events request.

channel.channel_id

The ID of the channel that triggered the notification.

channel.callback_url

The URL of the channel that triggered the notification.

channel.filters

Any non-default filters that were specified for the channel.

Expected response

A successful response must have a response code in the 2xx range and be returned within 5 seconds.

Therefore, anything that takes longer than 5 seconds to respond, or responds with a code not in the 2xx range will be treated as if it has failed.

We will continue to attempt to send the push notification for 24 hours. If no notifications succeed during this period then it is assumed that the channel is no longer valid and so the channel will be closed automatically and no further push notifications will be sent.


Create Notification Channel

Description

Creates a new channel for receiving notifications when changes occur.

Notification channels can be created with additional filters which can be thought of as a subset of those available when reading events.

URL format

api.cronofy.com/v1/channels

Example Request

POST /v1/channels HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "callback_url": {CALLBACK_URL},
  "filters": {
    "calendar_ids": [ "cal_n23kjnwrw2_sakdnawerd3" ],
    "only_managed": false
  }
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {
      "calendar_ids": [ "cal_n23kjnwrw2_sakdnawerd3" ],
      "only_managed": false
    }
  }
}

Request parameters

callback_url required

The HTTP or HTTPS URL you wish to receive push notifications.

Must not be longer than 128 characters and should be HTTPS.

filters.calendar_ids optional

Restricts the notifications to changes to events within the specified calendars.

The possible calendar_ids can be discovered through the list calendars endpoint.

If omitted, notifications are sent for changes to events across all calendars. When specified, at least one calendar_id must be provided.

filters.only_managed optional

A Boolean specifying whether only events that you are managing for the account should trigger notifications.

Response parameters

channel.channel_id

The ID of the channel.

Note that ID may be for an existing channel if you make a request to create a channel that is identical to an existing one.

channel.callback_url

The URL that will receive push notification requests.

channel.filters

Any non-default filters that were specified for the channel.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required callback_url parameter, you would receive a response like:

{
  "errors": {
    "callback_url": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.


List Notification Channels

Description

Returns a list of all the authenticated user's notification channels.

URL format

api.cronofy.com/v1/channels

Example Request

GET /v1/channels HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "channels": [
    {
      "channel_id": "chn_54cf7c7cb4ad4c1027000001",
      "callback_url": {CALLBACK_URL},
      "filters": {}
    }
  ]
}

Response parameters

channels.channel_id

The ID of the push notification channel.

channels.callback_url

The URL that will receive push notifications for the channel.

channels.filters

Any non-default filters that are specified for the channel.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.


Close Notification Channel

Description

Closes an existing push notification channel to stop notifications being sent.

URL format

api.cronofy.com/v1/channels/{CHANNEL_ID}

Example Request

DELETE /v1/channels/{CHANNEL_ID} HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 202 Accepted

Request parameters

CHANNEL_ID required

The ID of the push notification channel you wish to close.

Response parameters

This request has no response body.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.


UserInfo

Description

Returns identifying information for the authenticated account. This is defined as part of the OpenID spec.

URL format

api.cronofy.com/v1/userinfo

Example Request

GET /v1/userinfo HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "sub": "acc_5700a00eb0ccd07000000000",
  "cronofy.type": "account"
}

Response parameters

sub

This specifies the internal Cronofy ID for the account, as an ASCII-only String.

cronofy.type

This specifies the type of the account as a String.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.


Account Information

Description

Returns identifying information for the authenticated account.

URL format

api.cronofy.com/v1/account

Example Request

GET /v1/account HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "account": {
    "account_id": "acc_567236000909002",
    "email": "janed@company.com",
    "name": "Jane Doe",
    "scope": "read_events create_event delete_event",
    "default_tzid": "Europe/London"
  }
}

Response parameters

account.account_id

This specifies the internal Cronofy ID for the account, ASCII-only String.

account.email

The primary email address associated with the account as a String.

account.name

The name associated with the account as a String. May be null or blank.

account.scope

This specifies the scope granted for the account for the active authorization as a space-separated String in order to mimic how it is provided during an Authorization Request.

account.default_tzid

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.


Profile Information

Description

Returns a list of all the authenticated user's calendar profiles.

URL format

api.cronofy.com/v1/profiles

Example Request

GET /v1/profiles HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "profiles": [
    {
      "provider_name": "google",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "profile_connected": true
    },
    {
      "provider_name": "apple",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "profile_connected": false,
      "profile_relink_url": "https://app.cronofy.com/relink/apple?email=example@cronofy.com"
    }
  ]
}

Response parameters

profiles.provider_name

This specifies the provider of the calendar as a lowercase, ASCII-only String.

Currently one of:

  • apple
  • cronofy
  • exchange
  • google
  • live_connect
  • office365

However, this will be expanded over time and therefore consumers should support any value for this field.

This should be used to help a user distinguish between their profiles as they can have multiple profiles with the same name.

profiles.profile_id

This specifies the ID of the profile, a profile may consist of many calendars, as an ASCII-only String.

This is used for targetting other API actions toward this profile.

profiles.profile_name

This specifies the name of the profile as a String.

profiles.profile_connected

This specifies whether we have an active connection for this profile, usually whether we have valid credentials or not, as a Boolean.

profiles.profile_relink_url optional

When the profile is not connected, a URL will be provided as a String that you can direct the user to in order for them to reconnect this profile.

This URL is unique to each profile as it contains information relating to the underlying provider and so forth.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.