Toshl Developer

API Overview

API is currently in beta. This means things are bound to change, and change fast. Keep an eye on the changelog to stay up to date.

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

API uses OAuth 2.0 for authorization on all endpoints.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

All currencies are returned in ISO 4217 format.

USD, GBP, EUR ...

Use appropriate HTTP methods to achieve the desired result:

GET Fetch an object or list of objects.
POST Create a new object or call a method.
PUT/PATCH Update an object.
DELETE Delete an object.

Updating/Deleting an object

Whenever updating or deleting an object be sure to include an If-Unmodified-Since header or you will receive a 400 Bad Request error response. This way we can resolve most of the conflicts on the server. 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 object again and show the differences to the user and let her decide what the appropriate action should be.

Hypermedia

Toshl API strives to eventually become a Hypermedia-driven API. Because of this we have implemented a fixed URL structure for API endpoints and opted for versioning through media types.

To get a list of all available endpoints make a request to https://api.toshl.com and you’ll receive a complete list of available endpoints in the body.

GET https://api.toshl.com/
HTTP/1.1 200 OK
{
    "links": [
        {
            "rel": "me",
            "href": "\/me"
        },
        {
            "rel": "months",
            "href": "\/months"
        },
        {
            "rel": "expenses",
            "href": "\/expenses"
        },
        ...
    ]
}

All our API objects contain a links parameter that includes all the relevant linked objects or object lists. Each links object contains a href and rel parameter, where href is contains the URI of the object or object list and rel defines the meaning of the link.

Possible rel values

self Link back to the current resource.
month Link to current month overview.
expenses Link to a list of related expenses.
incomes Link to a list of related incomes.
budgets Link to a list of related budgets.
tags Link to a list of related tags.

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

{
    "id": "42",
    "name": "coffee",
    "modified": "2012-09-04T13:55:15Z",
    "count": 4,
    "links": [
        {
            "rel": "self",
            "href": "/expenses/tags/42"
        }
    ],
    "extra": null
}

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[.version]+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.beta+json

The current version of the API is beta.

Pagination

A user can have a large amount of data, so not to overwhelm the client, listing endpoints support pagination. By default only 30 of the most recently changed objects 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.

GET https://api.toshl.com/expenses?page=1
HTTP/1.1 200 OK
Link: </expenses?page=2>; rel="next",
      </expenses?page=9>; rel="last"
      ...

Possible rel values

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.

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/expenses
HTTP/1.1 200 OK
...
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
...
X-RateLimit-Limit Allocated request limit.
X-RateLimit-Remaining Number of requests remaining before limit is reached.

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.

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 Toshl objects. Whatever you do, the data will remain private to the user and your app.