API filtering & searching

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

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> .

Field Description
Page Int input, i.e. page = 1
Size Int input, i.e. size=100

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.

Field Description
Sort String input, i.e. sort= date-

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]

Field Description
Filter.Code String input, represents a field for filtring subscriptions by code

[GET /subscriptions/{subscriptionId}/metrics]

Field Description
Filter.From Date-time input, represents a field for filtering metrics by date as a starting point i.e. 2017-11-18T12:01:33+03:00
Filter.To Date-time input, represents a field for filtering metrics by date as an ending point i.e. 2017-11-18T12:01:33+03:00

[GET /subscriptions/all/metrics]

Field Description
Filter.From Date-time input, represents a field for filtering metrics by date as a starting point i.e. 2017-11-18T12:01:33+03:00
Filter.To Date-time input, represents a field for filtering metrics by date as an ending point i.e. 2017-11-18T12:01:33+03:00

Contact Calls

[GET /subscriptions/{subscriptionId}/contacts]

Field Description
Filter.Code String input, represents a field for filtering contacts by code

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

Field Description
Filter.Customers Boolean input, (true/false i.e. true to search customers)
Filter.Suppliers Boolean input, (true/false i.e. true to search suppliers)
Filter.Code String input, represents a field for filtering companies by code

Documents Calls

[GET /subscriptions/{subscriptionId}/documents]

Field Description
Filter.Number String input, represents a field for filtering documents by number
Filter.From Date-time input, represents a field for filtering documents by date as a starting point i.e. 2017-11-18T12:01:33+03:00
Filter.To Date-time input, represents a field for filtering documents by date as an ending point i.e. 2017-11-18T12:01:33+03:00
Filter.Status String input, (available options: Draft/Issued/Overdue/Partial/Paid/Void/Deleted)
Filter.RecipientCode String input, represents a field for filtering documents by recipient code
Filter.RecipientId String input, represents a field for filtering documents by recipient id
Filter.TypeId String input, represents a field for filtering documents by type id
Filter.PaymentCode String input, represents a field for filtering documents by payment code
Summary Boolean input (true/false)

Organisation Calls

[GET /subscriptions/{subscriptionId}/organisations]

Field Description
Filter.Customers Boolean input (true/false)
Filter.Suppliers Boolean input (true/false)
Filter.Code String input, represents a field for filtering organistions by code
About INDICE

Have something to say? Send us a message.

For any legal issues or if you believe that incontrl infringes your privacy in any way, please contact our Legal & Privacy Officers.

Offices
22, Iakchou Str Athens, 11854 Greece
Copyright
© INDICE 2014 - 2019 All rights reserved. Oh and don't read the next sentence! You little rebel, we like you :)