API Overview

All endpoints must be accessed over HTTPS. Currently only JSON responses are supported.

Formats

Wherever possible Toshl API returns standardized formats to avoid confusion.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

The exception to this rule is the modified date, which is to be used as a opaque string (only stored and not parsed as it is used to compare versions internally), but is in the following format:

YYYY-MM-DD HH:MM:SS.SSS

All dates are returned in ISO 8601 format:

YYYY-MM-DD

All currencies are returned in ISO 4217 format.

USD, GBP, EUR ...

Verbs

Use appropriate HTTP methods to achieve the desired result:

Authentication

API uses two types of authentication:

• OAuth2 bearer tokens.
• Basic authentication using long living tokens that you can generate in your account settings.

Your users can always revoke access to your application, so make sure your clients can recover.

Hypermedia

Toshl API strives to eventually become a Hypermedia-driven API. Because of this our API endpoint data is modeled using JSON Hyper-Schema which enables you to build clients that need to know very little about our endpoint structure, related resources and date formats - it is all included in a simple JSON document. When you make a request to an endpoint, the response header will include the schema document location.

Content-Type: application/vnd.toshl+json; profile=https://api.toshl.com/schema/expense#

Each endpoint has a different list of related resources, all of which are included in the schema in the links object.

We also provide the id parameter for most resources which is unique and can be used as the primary key in your internal database.

For more information on JSON Hyper Schema please refer to the specification.

Media Types

API uses special vendor media types that indicate version and response format. You can use it to target specific response versions by including it in the Accept header of your requests.

application/vnd.toshl+json

You can omit the version part of the media type to receive the most recent response version.

application/json
application/vnd.toshl+json

If you care about the version of the response, include a more specific media type.

application/vnd.toshl+json; version=1, application/json

The current version of the API is 1.

Pagination

A user can have a large amount of data, so not to overwhelm the client, listing endpoints support pagination. By default only 200 of the most recently changed resources are returned per page. That limit can be changed by setting the per_page parameter for the request. The response contains additional pagination information in the HTTP Link header. As with everything in programming, the pages start with 0 - but you need not know this, since the API will return the correct pages for paging in Links.

GET https://api.toshl.com/entries

HTTP/1.1 200 OK
Link: </entries?page=1>; rel="next",
      </entries?page=9>; rel="last"

Possible rel values

Rate limiting

API is rate limited, meaning that your application can make only a finite number of requests in a given period. To see your limit and the number of remaining requests check the X-RateLimit-Limit and X-RateLimit-Remaining response headers or check the rate limit status endpoint.

GET https://api.toshl.com/entries

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

Limit status

You can always check the rate limit status by checking the response headers or by issuing a request to /rate-limit.

GET https://api.toshl.com/rate-limit

{
    "limit": 1000,
    "remaining": 998
}

Note: The endpoint /rate-limit is not rate limited.

Updating a resource

Whenever updating a resource be sure not to modify the readonly modified parameter or you will receive a 400 Bad Request error response. We will try to resolve most of the conflicts on the server, but if you run into a situation where we are unable to do that automatically a 409 Conflict error will be returned. In that case we recommend you download the resource again and show the differences to the user and let her decide what the appropriate action should be.

null and empty values

The API by default does not return null values and empty arrays. Make sure that your client understands that the absense of a field means that field has no value, not that it hasn’t been changed. The same goes for sending data to the API: if you omit the field, that value has been removed/unset.

Exchange rates

While the API offers access to a list of supported currencies we do not offer a list of currency exchange rates. We recommend you use a service similar to the awesome Open Exchange Rates, which we already use in our own apps.

Extend

You can extend Toshl API with the use of the extra parameter, which is available for most API endpoints. Whatever you put into this field you will get back when you fetch it later. Use it to map you data from Toshl to your system or to add more information to resources. Whatever you do, the data will remain private to the user and your app.