# Teamup.com API Documentation This API allows programmatic access to calendars hosted by [Teamup](https://teamup.com). The API endpoints described here are the only ones we currently officially support and intend on maintaining backwards compatible. As such if you use any other URL you have to understand you are doing so at your own risk. If the API endpoints described here are not sufficient for your requirements, please [get in touch with us](mailto:support@teamup.com) and we will be happy to discuss further integration points. Usage of the API is included in the [subscription plans](http://www.teamup.com/pricing/) offered for Teamup. There is no additional fee. We only ask you to register your application by [requesting an API key for free](https://teamup.com/api-keys/request). This provides us with a means to contact you, should the need arise to do so. ## General API Guidelines - API access MUST be done over **TLS/SSL** via https://api.teamup.com/ - All API requests must include an [API key](#api-key) in a request header - Strings in requests and responses MUST be using the **UTF-8** character set - **Successful** responses will have status codes in the 200-299 range - **Client errors** will have status codes in the 400-499 range - **Server errors** will have status codes in the 500-599 range - **Placeholders** in URL examples are indicated by curly braces, e.g. `{eventId}` - API responses are in **JSON** using the `application/json` content type Please also take a look at the [API Usage Best Practices](#api-usage-best-practices). ## Querying the Teamup API ### API Key > Example: ```php ['Teamup-Token' => 'API_KEY']]); $result = $client->get('https://api.teamup.com/ks73ad7816e7a61b3a/events'); print $result->getStatusCode(); // "200" print $result->getHeader('content-type'); // 'application/json' print $result->getBody(); // {"events":[ ... ]} ``` ```shell curl "https://api.teamup.com/ks73ad7816e7a61b3a/events" \ -H "Teamup-Token: API_KEY" ``` Every request to the API must include an API key in a request header. We ask you to register your application by [requesting an API key for free](https://teamup.com/api-keys/request). This provides us with a means to inform you about changes to the API or contact you, should the need arise to do so.

You must replace API_KEY in all examples with your API key.

### Calendar Key Almost all API requests require a calendar key as part of the request URL. For example, to read a list of events the following API request is used: **`GET /{calendarKey}/events`** `{calendarKey}` addresses a specific calendar. One calendar can have many calendar keys and each calendar key has associated permissions, for example read-only, modify or administration. For each API endpoint you find the needed permission in the documentation of that endpoint. Calendar keys are managed using the Web-based calendar settings application. Look for the *Sharing* tab. ### API Clients The API can be queried using any HTTP client. Our documentation provides [PHP](//www.php.net) and [cURL](//curl.haxx.se/) examples. The PHP examples use the [Guzzle](//guzzlephp.org) library (version 6). You can install it in your project using Composer by running: `composer require 'guzzlehttp/guzzle:^6.0'` ## Testing your API key > Example: ```php ['Teamup-Token' => 'API_KEY']]); $result = $client->get('https://api.teamup.com/check-access'); print $result->getStatusCode(); // "200" ``` ```shell curl "https://api.teamup.com/check-access" \ -H 'Teamup-Token: API_KEY' ``` > Expected response: ``` 200 OK { "access": "ok" } ``` This endpoint lets you check if your API key is valid and you are submitting it as expected. ### HTTP Request **`GET /check-access`** ## Querying password-protected calendars > Example: ```php [ 'Teamup-Token' => 'API_KEY', 'Teamup-Password' => 'demopassword' ]); $result = $client->get('https://api.teamup.com/kscb1caefc73e9f0a8/events'); print $result->getStatusCode(); // "200" print $result->getHeader('content-type'); // 'application/json' print $result->getBody(); // {"events":[ ... ]} ``` ```shell curl "https://api.teamup.com/kscb1caefc73e9f0a8/subcalendars" \ -H 'Teamup-Token: API_KEY' -H 'Teamup-Password: demopassword' ``` For password-protected calendars, you must send a custom `Teamup-Password` header that has the password as value.

You must replace demopassword with your password.

## Querying the API using cURL on Windows If you use the **cURL** samples in Windows's cmd.exe, and want to POST JSON data, you will have to escape the JSON text. For example use `curl ... -d "{""json"": ""data""}"` with all the double quotes appearing twice within the string. On Linux or using cygwin cURL builds this is not an issue as you can quote using single quotes (`'`) to avoid having to escape the double quotes. The other thing to take into account is that by default your cURL might not come with an SSL CABundle, which prevents it from making secure connections to us, and it will warn you about a self-signed certificate. The solution is to download a [CA bundle](https://curl.haxx.se/ca/cacert.pem) and save it next to curl.exe, with the file name `curl-ca-bundle.crt` (don't forget to change the extension from .pem). This will give cURL the knowledge about root certificate authorities, which will allow it to validate our SSL certificate against it. You should ideally keep this file updated reasonably often to make sure any revoked certificates are removed and new ones added. ## Querying the API via JavaScript / CORS > Example: ```js // Creates a CORS request in a cross-browser manner function createCORSRequest(method, url) { var apiKey = 'API_KEY'; var xhr = new XMLHttpRequest(); if ("withCredentials" in xhr) { // XHR for Chrome/Firefox/Opera/Safari/IE10+. xhr.open(method, url, true); xhr.setRequestHeader('Teamup-Token', apiKey); } else if (typeof XDomainRequest != "undefined") { // XDomainRequest for IE8/IE9. xhr = new XDomainRequest(); // XDomainRequest does not support querying HTTPS from HTTP pages if (window.location.protocol === 'http:') { url = url.replace('https://', 'http://'); } if (-1 === ['GET', 'POST'].indexOf(method)) { alert('XDomainRequest only supports GET and POST methods'); return; } if (-1 === url.indexOf('?')) { url += '?_teamup_token=' + apiKey; } else { url += '&_teamup_token=' + apiKey; } xhr.open(method, url); } else { // CORS not supported. xhr = null; } return xhr; } // Sends the actual CORS request. function makeCorsRequest(url, successCallback, errorCallback) { var xhr = createCORSRequest('GET', url); if (!xhr) { alert('CORS not supported'); return; } // Response handlers. xhr.onload = function (xhr) { if (xhr.target.status < 400) { if (successCallback) successCallback(xhr.target); } else if (errorCallback) { errorCallback(xhr.target); } }; xhr.onerror = function (xhr) { if (errorCallback) { errorCallback(xhr.target); } }; xhr.send(); } // Send a GET request for all events in a date range makeCorsRequest( 'https://api.teamup.com/ks73ad7816e7a61b3a/events?startDate=2015-06-01&endDate=2015-06-05', function(xhr) { var data = JSON.parse(xhr.responseText); alert('Successfully Received: ' + JSON.stringify(data)); }, function(xhr) { var data = JSON.parse(xhr.responseText); alert('Request failed with code '+ xhr.status +': ' + JSON.stringify(data)); } ); ``` The Teamup API supports [Cross-Origin Resource Sharing](http://enable-cors.org/) requests. This is the preferred way and is widely supported across all browsers. If you do ajax requests with jQuery for example it will use CORS by default and everything should work out of the box. If you wish to do it with pure JS you can use the code snippet on the right to make it work across browsers. Note that **IE8** and **IE9** only support XDomainRequest and not the full CORS specification. If you need to support those versions, be mindful of the following limitations: - You can only use the **GET** and **POST** method - If your site is hosted on **http** and not **https**, you must query our API using **http** as well - You can not set **custom headers**, this means that the key has to be passed using a `_teamup_token` query parameter, e.g. `?_teamup_token=API_KEY` The code above takes care of most of these for you but supporting IE8/9 will still restrict your usage. To use the full API you can write a simple server-side script to proxy your requests to the Teamup API via your server and then use regular `XMLHttpRequest` calls. ## Date and Time Formats All parameters and properties of type date and/or time follow the [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601) standard on date and time formats. Example | Description ----------------------------|--------------------------------- `2015-01-31` | Date only `2015-01-31T10:00:00` | Date and time, default timezone `2015-01-31T10:00:00Z` | Date and time, timezone UTC `2015-01-31T10:00:00-05:00` | Date and time, timezone -05:00 **Default Timezone** If timezone is not specified, then the default timezone is assumed. The default timezone is: 1. The timezone defined by the [tz query parameter](#global-query-parameters) or 2. The calendar's default timezone as specified in the calendar's configuration ## Global Query Parameters The following query parameters are available for all API end points: Parameter | Type | Default | Description --------- | ---- | ------- | ----------- tz | string | Calendar timezone | The request timezone. Supported timezones include: `UTC`, `America/New_York` and equivalent (see [TZ database timezones](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a full list). Note that this parameter is only respected by the server if the calendar is configured to allow users changing the timezone. See Settings -> Date & Time of your calendar. lang | string | Calendar language | The language to use in responses. Currently supported values are en, en_GB, fr, de, etc. See [User.language](https://teamup.stoplight.io/docs/api/c2NoOjI2Njc4ODM1-user) for the complete list.