API Overview
TeamWork Live supports programmatic interaction with your data via a HTTP-based REST API. You can use the API to integrate TeamWork Live with third-party applications, dashboard widgets, or your own custom software.
What is an API?
An API is an acronym for Application Programming Interface. APIs allow for the the sharing of content and data between applications by making it easy to programmatically retrieve data from one application and update it in another application.
Technical Information
The API is HTTP-based and conforms to the design principles of Representational State Transfer (REST). API calls require the use of the correct HTTP request method (GET/PUT/POST/DELETE):
- Calls that retrieve data from the API require a GET request.
- Calls that create data require a POST request.
- Calls that modify or update data require a PUT request.
- Calls that delete data require a DELETE request.
API calls will return an error if you do not make your request with the correct method.
The API currently supports getting data in JSON and XML format. Simply change the format extension of a request to get results in the format of your choice. Add .json to the end of the request to get the response back in JSON format and add .xml to the end of the request to get the response back in XML format.
Usage
Use the links on the left to view the supported API calls. Each API call will include example requests and responses. The response will show actual data from your account. If you do not have any data for a specific call, the response will be empty until you populate your account with the appropriate data. For example, a call to retrieve client companies will return no data if you have not set up any client companies. The examples will be given using the command line tool cURL. However, any HTTP library or client could be used to interact with the API.
Authentication
API requests are authenticated using HTTP Basic Authentication. Your authentication credential consists of the email address associated with your account and your API key. An HTTP response of "401 - Unauthorized" will be returned for missing or incorrect authentication credentials. Please note that your API key will change if your password is updated.
Requests
Requests that include a message body must specify the message format by including a "Content-Type" HTTP header that indicates the format of the body content (i.e., application/json for JSON and application/xml for XML).
Some API calls accept optional request parameters. When making requests with parameters, ensure that the parameter values are UTF-8 and URL encoded.
Responses
HTTP response codes are used to indicate the result of the request.
| 200 - OK | The request was successful. |
| 201 - Created | The resource was successfully created. |
| 401 - Unauthorized | The credentials submitted via HTTP Basic Authentication was missing or incorrect. |
| 400 - Bad Request | The request body was malformed or the field you are trying to update contains an invalid value. You should look in the message in the response for the list of errors. |
| 403 - Forbidden | You do not have permission to create, modify, or access the specified resource. |
| 404 - Not Found | The resource you are trying to retrieve does not exist. |
| 500 - Internal Server Error | There was an error in the API. This is likely caused by a bug in the API code. Support automatically receives notifications of these errors and they should be addressed shortly. |
| 503 - Service Unavailable | You have exceeded the maximum number of API calls allowed per hour. See below for more information. |
Rate Limit
Usage of the API is rate-limited. You are allowed to perform up to 6000 requests per hour from each user account. If you exceed this limit, you'll get a "503 - Service Unavailable - Rate Limit Exceeded" response. Check the "Retry-After" header in the response for information on when you can make your next request.
If you have a valid need for exceeding the rate limit, please contact us at support@teamworklive.com to request a higher limit.
