#
Include

For all GET endpoints you can include only the properties you want via the include parameter.

You can do it two ways:

Include approach - include everything except chosen properties.
Exclude approach - exclude everything except chosen properties.

#
General rules

By default for every object (including relations) you'll get all primitive properties. By primitive properties we mean all non-relation properties such as string, number, boolean, jsonb and date properties. For example: account_id (string) is included, while account (relation) is not.

GET /balances/{id}
Result
{
  "id": "1f770c58-2393-4b49-bfb6-43f3766cb066",
  "identifier": "a",
  "name": "Main balance",
  "description": "This is the main balance of the account",
  "account_id": "c2b81c5a-1f18-4f5d-bdc0-85a64dd8d79d",
  "unit_id": "51edd301-761b-4561-a8a9-b61a627c387b",
  "type" : "main",
  "balance": "52.00",
  "available_balance": "52.00",
  "negative_balance": "52.00",
  "external_id": null,
  "variables" : null,
  "created_at": "2022-10-05T14:48:00.000Z",
  "updated_at": "2022-10-05T14:48:00.000Z",
  "archived_at": null
}

Note that include syntax doesn't affect id - it is always included.

#
Include approach

As with filters, include follows JSON format. To include only name of the balance do following.

GET /balances/{id}?include={"name":true}
Result
{
  "id" : "6b91f9fc-2f0d-4bdb-86c8-f41bab748d49",
  "name": "Main balance"
}

It's the same to include related objects. Note that defaults will apply for that object. (i.e all primitives included by default). For example, to also include Unit:

GET /balances?include={"name":true, "unit": true }
Result
{
  "id" : "6b91f9fc-2f0d-4bdb-86c8-f41bab748d49",
  "name": "Main balance",
  "unit" : {
    "id" : "245088c9-ff7c-4b26-b4ae-6d512c01498c",
    "name": "USD",
    "description" : "United States Dollar",
    "max_precision" : 2,
    "default_precision" : 2,
    "default_mode" : "floats",
    "workspace_id": "0b6496ce-fd62-4831-9c9f-341143b021ac",
    "background_color" : "#F0F0F0",
    "color" : "#49678D",
    "symbol" : "$",
    "created_at": "2022-10-05T14:48:00.000Z",
    "updated_at": "2022-10-05T14:48:00.000Z",
    "archived_at": null
  }
}

GET /balances?include={"name": true, "unit": { "name": true } }
Result
{
  "id" : "6b91f9fc-2f0d-4bdb-86c8-f41bab748d49",
  "name": "Main balance",
  "unit" : {
    "id" : "245088c9-ff7c-4b26-b4ae-6d512c01498c",
    "name": "USD"
  }
}

And again, like with filters, we accept relaxed JSON so you can drop top-level { } brackets or not use quotes in JSON keys.

For example this will also work.

GET /transactions?include=status:true

#
Exclude approach

To include everything except name of the balance do following:

GET /balances/{id}?include{"name":false}
Result
{
  "id": "1f770c58-2393-4b49-bfb6-43f3766cb066",
  "identifier": "a",
  "description": "This is the main balance of the account",
  "account_id": "c2b81c5a-1f18-4f5d-bdc0-85a64dd8d79d",
  "unit_id": "51edd301-761b-4561-a8a9-b61a627c387b",
  "type" : "main",
  "balance": "52.00",
  "available_balance": "52.00",
  "negative_balance": "52.00",
  "external_id": null,
  "variables" : null,
  "created_at": "2022-10-05T14:48:00.000Z",
  "updated_at": "2022-10-05T14:48:00.000Z",
  "archived_at": null
}

Same applies to related objects for example to also include Unit:

GET /balances/{id}?include{"name":false,"unit":{"name": false}}
Result
{
  "id": "1f770c58-2393-4b49-bfb6-43f3766cb066",
  "identifier": "a",
  "description": "This is the main balance of the account",
  "account_id": "c2b81c5a-1f18-4f5d-bdc0-85a64dd8d79d",
  "unit_id": "51edd301-761b-4561-a8a9-b61a627c387b",
  "type" : "main",
  "balance": "52.00",
  "available_balance": "52.00",
  "negative_balance": "52.00",
  "external_id": null,
  "variables" : null,
  "created_at": "2022-10-05T14:48:00.000Z",
  "updated_at": "2022-10-05T14:48:00.000Z",
  "archived_at": null,
  "unit" : {
    "id" : "245088c9-ff7c-4b26-b4ae-6d512c01498c",
    "description" : "United States Dollar",
    "max_precision" : 2,
    "default_precision" : 2,
    "default_mode" : "floats",
    "workspace_id": "0b6496ce-fd62-4831-9c9f-341143b021ac",
    "background_color" : "#F0F0F0",
    "color" : "#49678D",
    "symbol" : "$",
    "created_at": "2022-10-05T14:48:00.000Z",
    "updated_at": "2022-10-05T14:48:00.000Z",
    "archived_at": null
  }
}

#
Filtering on Included Models

There might be times when you include related nested objects and you want to filter on them.

For example to only include the balances of an account with an amount over 100.00 you can use the following query.

GET /accounts?include={balances: {where: {amount: {gt: '100'}}, include: {amount: true, name: true}}}

The nested include field is optional. It can be omitted entirely or provided as an empty object {}.

#
Restrictions

You cannot combine Include and Exclude approach for primitives on same level. However you can use them together on different levels.

For example this is not allowed:

GET /balances/{id}?include={"name": true, "description": false}

While this is allowed:

GET /balances/{id}?include={"name": true, "unit": {"name": false}}

And this is allowed (include all primitives except name and include relation unit:

GET /balances/{id}?include={"name": false, "unit": true}

#
Exceptions

Some properties that look primitive are actually computed and are not included by default.

An example of computed property is identifier (string) in Account. We don't store it in our database but auto-generate it from identifier_prefix + '-' + identifier_value.

So to include identifier alongside with default properties you have to explicitly specify include={"identifier": true}.

#Include

#General rules

#Include approach

#Exclude approach

#Filtering on Included Models

#Restrictions