Pagination

All the APIs that retrieve a set of entities return a paginated result. To handle pagination you can use two parameters:

• page=n indicates the page number you want to get
• itemsPerPage=m number of items per page (30 is the default value, 100 is the maximum)

For example:

GET /business-registry/a_fiscal_code/transactions?page=2&itemsPerPage=10

To get full information about the pagination you can send the HTTP header application/ld+json. You will receive an enriched payload that encapsulates the original result adding these keys:

• hydra:member - the array with the retrieved items
• hydra:totalItems - total filtered items
• hydra:view
  • hydra:first - URL to the first page
  • hydra:last - URL to the last page
  • hydra:next - URL to the next page
• hydra:search - object containing information about the filters

For example

{
  "@context": "/contexts/BusinessRegistry",
  "@id": "/business-registry",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@type": "BusinessRegistry",
      "@id": "/business-registry/EFGH",
      "fiscalId": "EFGH",
      "email": "foo2@bar.com",
      "businessName": "Foo two",
      "enabled": true
    }
  ],
  "hydra:totalItems": 3,
  "hydra:view": {
    "@id": "/business-registry?itemsPerPage=1&page=2",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/business-registry?itemsPerPage=1&page=1",
    "hydra:last": "/business-registry?itemsPerPage=1&page=3",
    "hydra:previous": "/business-registry?itemsPerPage=1&page=1",
    "hydra:next": "/business-registry?itemsPerPage=1&page=3"
  }
}

See Hydra specifications for more information.

Optional values

Our API does not return optional values if they are not present. For example, iban, bban and swift codes are not mandatory for Accounts, so the JSON representation for entities that do not have these values will not contain these fields at all:

{
  "uuid": "ad82d5c8-1d05-47eb-8696-3def0bc19243",
  "fiscalId": "xxxyyyyzzz",
  "accountId": "12345678",
  "providerName": "My Bank",
  "name": "John Smith",
  "nature": "card",
  "balance": "100.00",
  "currencyCode": "USD",
  "enabled": true,
  "consentExpiresAt": "2019-08-24T14:15:22Z",
}

Filtering data

Searching for multiple values

Some endpoints have query parameters of the form someName[]. That means you can filter data for multiple values of the parameter. For example:

/sample_endpoint?sampleParameter[]=SAMPLE_1&sampleParameter[]=SAMPLE_2

In this example we will get elements having sampleParameter=SAMPLE_1 or sampleParameter=SAMPLE_2.

Filtering using dates

Some endpoints can use filters on dates. This kind of filter have this form:

someDate[before]	
someDate[strictly_before]
someDate[after]
someDate[strictly_after]

Here is an example on how to get data in some range:

/sample_endpoint?someDate[strictly_after]=2022-01-03T02:03:24Z&someDate[strictly_before]2023-11-22T04:03:15Z

If you want to have different sets of email/password so that a particular Business Registry can handle just its data, maybe because you are developing an 'on premise' software, you can use sub-accounts. To do that you can create a new Business Registry, then you can assign it a user (i.e. a sub-account) with a particular password with a POST on the /business-registry/{fiscalId}/user endpoint. You can remove this assignment with a DELETE on the same endpoint. Connecting using the Business Registry email and the above password gives access just to data owned by this Business Registry. Your main login can still access data from all the Business Registries you created. Another way of creating a sub account that is equivalent to the previous one is via the authentication API.

Bank Managers entities represent persons that have access to bank accounts owned by different Business Registries. Explicit creation of Bank Managers is not mandatory for using the APIs. In fact, each time a connection request is made, a default Bank Manager is created (if one does not exist). Please note that in the above API you can optionally specify the email of a Bank Manager that will connect bank accounts. You can also link a new Bank Manager the Business Registry, hereby granting them permission to assign Accounts to it.

---