API design
Last updated
Last updated
Current version (2.0) of our API is available, for each API domain, at the following path:
In this documentation, all path references and examples are relative to this root.
Our API exposes a set of endpoints to interact with resources. Endpoint routes are named after the resources they interact with:
Path example | Resource |
---|---|
Deep paths are sometimes uses to access sub-resources:
Interactions with resources mostly follow conventions by using dedicated HTTP methods to perform operations:
Method | Operation |
---|---|
Not all operations are valid for every resource, API reference of each service describes the specific behaviors by endpoint.
We use various relevant HTTP response codes depending on the success or failure of the request. Successful responses (2XX status) return the entity documented with each endpoint in the services reference. Error responses (4XX and 5XX status) use a common error format.
Error handling should be preferably based on the error code rather than the HTTP status code.
Requests to the API, unless specified, should be formatted in JSON, with the appropriate content-type
request header.
For convenience, we also accept x-www-form-urlencoded
requests when the body does not imply nested levels.
Responses are exclusively returned as JSON objects, you can specify it using the recommended accept
request header.
On endpoints that allow access to a list of items, pagination is used to easily slice the results and navigate the whole collection.
Pagination relies on a limit on the number of returned items in a single API call, that can be set using the limit
query parameter.
Usage of the limit
parameter is advised for most resources, and mandatory for some (explicitly documented), in order to control the maximum number of returned items.
Except documented otherwise, limit
has a maximum value of 1000.
Most of collection endpoints accept an offset
parameters. Combine it with limit
to access arbitrary ranges of items.
Some paginated resources also return an easy-to-use _link
property with links to use for sibling loads.
Each of these link references is either null
(if there is no previous or next page), or is an object with an href
property, which is the URL of the relevant page (previous, current or next).
The provided links are opaque and should be used "as is", they encapsulate the filtering logic expressed by parameters on the initial request.
Some resources may be filtered using a temporal criterion on a property. In this case, the list endpoint usually support min_date
and max_date
parameters.
The value can be a date (in ISO YYYY-MM-DD format), but also a month or a year.
Some collections use soft-deletion or an enabled/disabled state. For these resources, implicit filtering is applied to exclude deleted or disabled resources from the default API responses. You can access the excluded items by adding the all
flag query parameter.
Example:
Most API calls support an expansion mechanism to enrich the response with linked sub-resources. This enables fetching a full set of data without performing multiple requests. Expansion is defined using the expand
query parameter with a comma-separated list of wanted sub-resources. Nested sub-resources are also available with brackets.
Example: The following request will return the bank account 123 with associated connection, the list of latest transactions (it is not possible to control pagination or filtering here), and for each transaction the associated category:
Each resource defines in its documentation the available expansions.
Code | Message | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Path | Resources |
---|---|
/connections/*
Manage connections
/accounts/*
Manage bank accounts
/auth/*
Common prefix for authentication services
GET /resources
List resources
GET /resources/{id}
Get a unique resource by id
POST /resources
Create a new resource
POST /resources/{id}
or PUT /resources/{id}
Update a resource
DELETE /resources/{id}
Delete a resource
200
OK
Defaut success code for responses.
202
Accepted
Alternate success code for requests that need further interaction to resume the operation (e.g. connection addition or sync).
204
No content
Success code for requests that return nothing.
400
Bad request
Error code when the request is invalid, e.g. the supplied parameters are incorrect.
401
Unauthorized
Error code when the service requires authentication and the proper header was incorrectly provided.
403
Forbidden
Error code when an authentication token with insufficient scope was provided to access an endpoint.
404
Not found
Error code when the route was incorrect, or the resource is unknown for the provided authorization scope.
409
Conflict
Error code when a request could not be honored because of a conflicting state with the API.
500
Internal servor error
Error code for failures related to internal bugs.
503
Service unavailable
Error code when our API is temporarily down for maintenance.
self
Link object
Reference to the current page (with a href
property).
prev
Link object or null
Reference to the previous page (with a href
property), if any.
next
Link object or null
Full address of the next page (with a href
property), if any.
/user/me/accounts
Return bank accounts that are not disabled.
/user/me/accounts?all
Return all bank accounts.
/user/me/accounts/123?all
Interact with the disabled account 123.