API design

Root and versioning

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.

Services design

Our API exposes a set of endpoints to interact with resources. Endpoint routes are named after the resources they interact with:

Path exampleResource


Manage connections


Manage bank accounts


Common prefix for authentication services

Deep paths are sometimes uses to access sub-resources:


Interactions with resources mostly follow conventions by using dedicated HTTP methods to perform operations:


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

Not all operations are valid for every resource, API reference of each service describes the specific behaviors by endpoint.

HTTP response codes

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.




Defaut success code for responses.



Alternate success code for requests that need further interaction to resume the operation (e.g. connection addition or sync).


No content

Success code for requests that return nothing.


Bad request

Error code when the request is invalid, e.g. the supplied parameters are incorrect.



Error code when the service requires authentication and the proper header was incorrectly provided.



Error code when an authentication token with insufficient scope was provided to access an endpoint.


Not found

Error code when the route was incorrect, or the resource is unknown for the provided authorization scope.



Error code when a request could not be honored because of a conflicting state with the API.


Internal servor error

Error code for failures related to internal bugs.


Service unavailable

Error code when our API is temporarily down for maintenance.

Error handling should be preferably based on the error code rather than the HTTP status code.

Requests and responses format

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.

Lists pagination

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.

Basic offset pagination

Most of collection endpoints accept an offset parameters. Combine it with limit to access arbitrary ranges of items.

Relational pagination

Some paginated resources also return an easy-to-use _link property with links to use for sibling loads.



Link object

Reference to the current page (with a href property).


Link object or null

Reference to the previous page (with a href property), if any.


Link object or null

Full address of the next page (with a href property), if any.

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.

GET /users/me/transactions?min_date=2022-12-01&income=false&limit=50
  "transactions": [ ... ],
  "_links": {
    "prev": null,
    "self": {
      "href": "https://{domain}.biapi.pro/2.0/users/me/transactions?min_date=2022-12-01&income=false&limit=50"
    "next": {
      "href": "https://{domain}.biapi.pro/2.0/users/me/transactions?min_date=2022-12-01&income=false&limit=50&cursor=W3sib3AiOiAibHQiLCAidmFsdWUiOiAiMjAyMC0wMy0wOCJ9LCB7Im9wIjogImd0IiwgInZhbHVlIjogOTgwNzg3fV0="

Lists temporal filtering

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.

Lists implicit filtering

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.




Return bank accounts that are not disabled.


Return all bank accounts.


Interact with the disabled account 123.

Response expansion

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:

GET /users/me/connections/123?expand=accounts,connector[countries]
  "id" : 123,
  "state": null,
  "accounts": [
    { "id": 1234, "name": "Current account", "disabled": "2020-06-01 12:34:56", … },
    { "id": 4567, "name": "Saving account", "disabled": "2020-06-01 12:34:56", … },

  "connector" : {
    "id": 40,
    "name": "Connecteur de test",
    "auth_mechanism": "credentials",
    "capabilities": [ "bank", "document", "profile", … ],
    "countries": [ { "id": "fr", "name": "France" }, … ]


Each resource defines in its documentation the available expansions.

Last updated