All endpoints must be accessed over HTTPS. Currently only
JSON responses are supported.
Wherever possible Toshl API returns standardized formats to avoid confusion.
All timestamps are returned in ISO 8601 format:
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:
All dates are returned in ISO 8601 format:
All currencies are returned in ISO 4217 format.
USD, GBP, EUR ...
Use appropriate HTTP methods to achieve the desired result:
|GET||Fetch a resource or list of resources.|
|POST||Create a new resource or call a method.|
|PUT/PATCH||Update a resource.|
|DELETE||Delete a resource.|
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.
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
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.
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.
You can omit the version part of the media type to receive the most recent response version.
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
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
|first||Link to first page of results.|
|previous||Link to previous page of results.|
|next||Link to next page of results.|
|last||Link to last page of results.|
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-Remaining response headers or check the rate limit status endpoint.
|X-RateLimit-Limit||Allocated request limit.|
|X-RateLimit-Remaining||Number of requests remaining before limit is reached.|
You can always check the rate limit status by checking the response headers or by issuing a request to
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.
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.
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.