Calamari API Documentation
Calamari offers a public web API, with which you can manage absences and timesheet entries.
- UTF-8 encoding is used in every request and server response
- Only JSON format is used in every request and response
- Every request should be made using HTTPS
- If an employee identifier is required, please provide e-mail or Calamari user login
- Usage of this API is limited. You can make 20 requests/second, 1500 requests/hour, 10000 requests/day. If you need more contact with us.
Before you can use Calamari API, you have to enable "API Access" in configuration panel.
Please keep generated ApiKey in secret.
Every method in this API is authenticated using HTTP Basic Authentication (more info
- As username use "calamari".
- As password use API_KEY_FROM_CONFIGURATION_PANEL.
Returned HTTP status code indicates method result. In general:
- 2xx - Request successful.
- 4xx - Api usage errror. Can be fixed by changing request parameters.
- 5xx - Server error. Something wrong happened in Calamari backend. Please wait a while and repeat your request.
In particular, you should implement:
- 200 - Request successful. More information is returned in json object. Object schema depends on method.
- 201 - Request successful. No result returned.
- 400 - Error occurred. Additional information provided in json response (ErrorResponse format: more info below)
- 401 - Authentication failure. There are two possible reasons: disabled API access or invalid ApiKey provided
- 403 - Access forbidden
- 404 - Invalid method URL
- 405 - HTTP method not allowed, please verify HTTP method of the request
- 429 - Too many requests in a given amount of time. API limits are 20 requests/second, 1500 requests/hour, 10000 requests/day
- 5xx - Something wrong happened in Calamari backend. Please wait a while and repeat your request. If error still occurs, drop us a line.
If status 4xx is returned, you can read additional information from returned json object.
- message - Human readable error explanation.
- code - Error code. Possible value depends on method but there is few common error codes.
- field - Which field of payload object caused error. NULL when error is not related to particular field
Common error codes:
- AUTH - Authentication failure. There are two possible reasons: disabled API access od invalid ApiKey provided. Used when returned HTTP status code is 401.
- HTTP_METHOD_NOT_ALLOWED - HTTP method not allowed, please verify HTTP method of the request. Used when returned HTTP status code is 405.
- INVALID_METHOD_URL - HTTP method not allowed, please verify HTTP method of the request. Used when returned HTTP status code is 404.
- QUOTA_EXCEEDED - Too many requests in a given amount of time. Used when returned HTTP status code is 429.
- INVALID_JSON_PAYLOAD - Json object you sent cannot be interpreted by server. Please check object format and provided data due to api specification.
- UNKNOWN_ERROR - We don't know what happened but will investigate.
Responses and requests objects can be extended. If you cannot recognize a json object attribute, just ignore it.