Expand Results

Some Sibill API endpoints support the optional expand parameter, which allows the client to request related resources directly within the response. This reduces the need to make multiple API calls.

How to use it

Expansions must be passed as parameters in the query string using the following syntax:

expand=resource1 or expand=resource1,resource2 (URL-encoded if included in a raw URL, e.g. category,subcategory → expand=category%2Csubcategory)

Where resource1, for example, is the name of the resource you want to expand.

Note: In the documentation for each individual endpoint you will find the list of resources that can be expanded along with their schema.

Practical example

Consider a request to get transactions with their related categories and subcategories expanded:

GET /api/v1/companies/:company_id/transactions?expand=category%2Csubcategory

HTTP/1.1 200 OK
Content-Type: application/json

{
   "data":[
     {
       "id": "82e1845f-14ac-927b-99a6-3cffc6109456",
       "date": "2025-05-06T13:20:45.589000Z",
       "description": "Transfer payment: Invoice n. 1 of 01/05/2025",
       "category": {
         "id": "cb00f116-e2bb-4824-81ab-ac3fa3a801eb",
         "name": "Outgoing"
       },
       "amount": {
         "currency": "EUR",
         "amount": "-220.72"
       },
       "created_at": "2025-05-02T17:34:57.432389Z",
       "account_id": "1f1276at-74ea-48de-a0d4-ea2538e284bt",
       "counterpart_name": "COUNTERPART SRL",
       "booking_date_time": "2025-05-06T13:20:45.589000Z",
       "clean_description": "Invoice N. 101 of 05/05/2025",
       "value_date_time": "2025-05-12T13:20:48.276000Z",
       "subcategory": {
         "id": "cb00f116-e2bb-4824-81ab-ac3fa3a801eb",
         "name": "Outgoing Invoices"
       }
     },
      ...
   ],
   "page":{
      "cursor":"g3QAAAACdwJpZG0AAAAkYzg3ZTNiYmMtYzNhZi00ZmFjLThkNzYtNmE1MTgzMDRhYdw1pY3JvkYXJ3E0NQRjEyAA==",
      "size":25
   }
}