API filtering & searching

The main goal of this document is to explain how to use filtering, paging and sorting.

Quicklinks

• Intro
• Paging - How to
• Sorting - How to
• Filtering - How to
• Subscriptions Calls
• Contact Calls
• Documents Calls
• Organisation Calls

Intro

Incontrl API returns lists as result sets. A ResultSet includes two fields, the count field that return the size of the result set and the items field that consists of the actual data.
Let's see an actual response of a GET subscription request.

{
  "count": 2,
  "items": [
    {
      "id": "ee2ad084-e695-4099-abc8-61336731e005",
      "alias": "demo-corp",
      "timeZone": "Europe/Athens",
      "status": "Enabled",
      "company": {
        "id": "f0fb2663-ef3f-4dc1-e4a5-08d51d4d4b98",
        "logoPath": "https://vignette2.wikia.nocookie.net/newdcmovieuniverse/images/e/ea/Wayne-enterprises-logo-large.png/revision/latest?cb=20130604235641",
        "name": "Wayne Corp",
        "legalName": "Wayne Enterprises, Inc.",
        "lineOfBusiness": "Manufacturing & vigilante services",
        "taxCode": "EL000000024",
        "taxOffice": "Gotham",
        "currencyCode": "EUR",
        "address": {
          "name": "Old Wayne Tower",
          "line1": "1 Corolla Building",
          "city": "Gotham City",
          "zipCode": "NJ 7001",
          "countryCode": "GR",
          "country": "Greece"
        },
        "email": "info@acme.gr",
        "website": "www.acme.gr",
        "paymentMethods": []
      },
      "contact": {
        "id": "0d7550c3-9cdf-46d5-436d-08d51d4d4ba1",
        "displayName": "Batman",
        "firstName": "Bruce",
        "lastName": "Wayne",
        "email": "bruce@wane-enterprises.fiction",
        "phone1": "+306900000000",
        "skype": "bat"
      }
    },
    {
      "id": "93172329-4371-4df4-9f0c-30d9e1f802a8",
      "code": "my-sandbox-01",
      "alias": "makis-stavropoulos-1",
      "timeZone": "Europe/Athens",
      "status": "Enabled",
      .......
    }
  ]
}

All lists solve three main concerns:

1. How to solve the paging problem.
2. How to do sorting.
3. How to do filtering.

curl -H "Accept: application/json" -X GET \
https://api.incontrl.io/subscriptions/my-alias/documents?filter.from=2017-11-24T10%3A47%3A47%2B03%3A00&
                                                         filter.to=2017-11-30T13%3A13%3A09%2B03%3A00&
                                                         filter.status=Void&
                                                         page=1&
                                                         size=100&
                                                         summary=true 

In the URL above, we filter the result set in order to return documents for a specific period ?filter.from=2017-11-24T10%3A47%3A47%2B03%3A00&Fflter.to=2017-11-30T13%3A13%3A09%2B03%3A00, for a specific status filter.status=Void, for a specific page page=1 and size size=100. We also enable the summary field to be returned in the response via summary=true. All these filters help users view the results in the desired format and also decrease load times.

Paging - How to

The API provides a feature for paging for all entities list and helps users view, chunks of data. We use two field to achieve that. The first is the page field and we use it for filtering by page. It takes only int inputs and the syntax for the URL is the following ?Page=<int input> . The second is the size field and we use it for filtering by a specific number (size) of records. It also takes int inputs with the syntax being the same as before ?size=<int input> .

An example of a request URL is the following:

curl -H "Accept: application/json" -X GET \
      https://api.incontrl.io/subscriptions?page=1&size=100

And the response:

{
  "count": 2,
  "items": [
    {
      "id": "ee2ad084-e695-4099-abc8-61336731e005",
      "alias": "demo-corp",
      "timeZone": "Europe/Athens",
      "status": "Enabled",
      "company": {
        "id": "f0fb2663-ef3f-4dc1-e4a5-08d51d4d4b98",
        "logoPath": "https://vignette2.wikia.nocookie.net/newdcmovieuniverse/images/e/ea/Wayne-enterprises-logo-large.png/revision/latest?cb=20130604235641",
        "name": "Wayne Corp",
        "legalName": "Wayne Enterprises, Inc.",
        "lineOfBusiness": "Manufacturing & vigilante services",
        "taxCode": "EL000000024",
        "taxOffice": "Gotham",
        ....
    }
  ]
}

Sorting - How to

The incontrl API provides a feature for sorting in order to display records in ascending or descending order. Sort is a comma delimited property string path. The syntax for the URL is the following ?sort=<string input>. By default sort return results in ascending order (optionally you can use + after the string input). Otherwise for desceding order the - must be placed after the string. Note: it is not case sensitive. This means that you can write, for ascending order NumberPrintable+ / numberPrintable+ / numberprintable+ or NUMBERPRINTABLE to the field.

An example of a request URL is the following:

curl -H "Accept: application/json" -X GET \
      https://api.incontrl.io/subscriptions/my-alias/documents?page=1&
                                                               size=100&
                                                               sort=number-
                                                               &summary=false

And the response:

{
  "count": 2,
  "items": [
    {
       "id": "129af778-5a3c-4376-c0d0-08d537b8bc46",
      "typeId": "bdb827c0-d5af-42e0-6eac-08d51d4d4c27",
      "number": 2,
      "numberPrintable": "000002",
      "date": "2017-11-30T13:13:09+03:00",
      "dueDate": "2017-11-30T13:14:43.7344774+00:00",
      "status": "Void",
      "currencyCode": "EUR",
      "currencyRate": 1,
        ....
    }
  ]
}

Filtering - How to

The API supports filters for narrowing down the result set on each of the index pages. Filters are passed as URL parameters for HTTP GET requests, and you can add as many filters as you'd like to each request. Based on the request we can use numerous filters. Some filters are: code filter, from and to specific period filter, customers and suppliers filter. In more details for code filtering we use string inputs that represents a specific code. For filtering in specific period we use two fields "from" and "to", both of them are DateTime fields and we must use either the ISO 8601 syntax or the date time offset counterpart like so: yyyy-MM-ddTHH:mm:ss.fffzzz (note here that these date values should be URL encoded because they can contain URL special characters like : + etc.). For customers and suppliers filters we use boolean (true/false) inputs. Basically we use true to search for customers or suppliers. There as some specific filters only for document requests. We use number field for filtering documents by number and status field for filtering documents with specific status (the available options are: Draft/Issued/Overdue/Partial/Paid/Void/Deleted). We can also filter documents by recipient code, by recipient id or by specific payment code. All of them take string inputs.

An example of a request URL is the following:

curl -H "Accept: application/json" -X GET \
     https://api.incontrl.io/subscriptions/my-alias/documents?filter.number=1& 
                                                              filter.from=2017-11-24T10%3A47%3A47%2B03%3A00&
                                                              filter.to=2017-11-29T10%3A47%3A47%2B03%3A00&
                                                              filter.status=Issued&
                                                              page=1&
                                                              size=100&
                                                              summary=true

And the response:

{
  "summary": {
    "currencyCode": "EUR",
    "total": 3633.2,
    "subTotal": 2930,
    "totalOtherTax": -152.95,
    "totalSalesTax": 703.2,
    "totalPayable": 2777.05
  },
  "count": 1,
  "items": [
    {
      "id": "8f5fd012-cc51-4933-9346-08d532faae41",
      "typeId": "bdb827c0-d5af-42e0-6eac-08d51d4d4c27",
      "number": 1,
      "numberPrintable": "000001",
      "date": "2017-11-24T10:47:47+03:00",
      "dueDate": "2017-11-24T10:48:31.9152479+00:00",
      "status": "Issued",
      "currencyCode": "EUR",
      ......
      "totalPayable": 2777.05
    }
  ]
}

Subscriptions Calls

[GET /subscriptions]

[GET /subscriptions/{subscriptionId}/metrics]

[GET /subscriptions/all/metrics]

Contact Calls

[GET /subscriptions/{subscriptionId}/contacts]

[GET /subscriptions/{subscriptionId}/contacts/{contactId}/companies]

Documents Calls

[GET /subscriptions/{subscriptionId}/documents]

Organisation Calls

[GET /subscriptions/{subscriptionId}/organisations]