Working with Object lists

TX API supports working with endpoints that return arrays of objects, for example, cards, contracts, applications, restrictions, etc.

Sorting

To sort return results, the order parameter is used. The sorting schema as well as sorting parameters depend on the object. For example, a GET request to the /applications endpoint that returns a list of applications has the ApplicationsOrder sorting schema (to sort by application ID, in ascending or descending order, respectively):

"ApplicationsOrder": {
    "type": "string", 
     "enum": [
        "IdAsc", 
        "IdDesc"
    ]
}

The GET request with the sorting by application ID will be as follows:

GET
https://tx/v1/applications?order=IdAsc

Another example describes a GET request to the /subjects endpoint that returns a list of customers has the SubjectsOrder sorting schema (to sort by customer ID, reference ID, or Name):

SubjectsOrder": {
    "type": "string", 
    "enum": [
        "IdAsc", 
        "IdDesc", 
        "RidAsc", 
        "RidDesc", 
        "NameAsc", 
        "NameDesc"
    ]
}

Then the respective parameter to sort by customer name will be as follows:

GET
https://tx/v1/subjects?order=NameAsc

New sorting parameters may be supported in the upcoming versions. For details on the available sorting parameters, refer to the TX REST API specification.

Pagination

The pagination mechanism enables to return a certain number of objects at a time. This mechanism is controlled by using the following subfields of the page object in the request:

• offset – required offset against the top of the list (default value is 0)
• limit – number of records to be returned (default value is 100)

"page" {
    "offset" : 0,
    "limit" : 100
}

For example (it is also possible to use character codes %5B = "[", %5D= "]" if these characters are incorrectly passed in the request for some reason):

GET
https://tx/v1/cards?page[offset]=0&page[limit]=100
...
https://tx/v1/cards?page%5Boffset%5D=0&page%5Blimit%5D=100

A response with the pagination results (list of objects) also contains the boolean parameter hasMore that indicates whether more records to return are present (true value) or absent (false value). For example:

{
  "objects": [
    {...}
  ],
  "hasMore": true
}

Filtering

The filtering mechanism enables to return a specific range of objects that meet the specified filtering criteria. To filter objects, the parameters of the filter object are used in the request header.

A list of parameters depends on the object filtering schema. For example, the contracts endpoint has the filtering schema to filter contracts by customer ID, customer reference ID, contract type ID, contract type reference ID, contract status. The subjects endpoint enables selection by customer type (Person or Company) and filtering by first name, last name, birthdate, etc.

The text search is not case-sensitive (unless otherwise specified explicitly), wildcards are supported - the percentage sign (%) substitutes a group of characters and the underscore (_) substitutes one character. Attention! The percentage sign is also used in URL to represent (mask) special characters, so it should be correctly passed in URL ('%' character is coded as %25 in URL notation). For example, to list all customers with the last name starting with 'J', the following request should be used:

GET
https://tx/v1/subjects?filter[kind]=Person&filter[lastNameLike]=J%25

The following example describes a request to return active contracts (status parameter is set to Active) filtered by Contract type reference ID:

GET
https://tx/v1/contracts?filter[typeRid]=debitGold643&filter[status]=A