Working with lists

How to work lists in the ComplyAdvantage Mesh API

All list endpoints support pagination, filtering and sorting.

Pagination

List endpoints support pagination. Pagination is done with the following keys in the url parameters:

  • page_number=int- the page number. If not supplied, this will return the first page of results.
  • page_size=int - reflective of the amount of results you’d like on each page.

For example, if you would like the 2nd page of results with 10 results on the page from the list of Cases, you would use the following request:

GET /cases?page_number=2&page_size=10

Filtering

List endpoints support querying via url parameters. We support the following filtering scenarios:

  • By attribute (e.g., state, assignee etc)
  • By attribute on a sub-object (e.g., customers that have crypto products)
  • By range (e.g., date, amount etc)
  • By presence of child or parent (e.g., cases that have notes)

By attribute
This is done via URL parameters using the keys in the underlying key in the object. For example,

GET /cases/?assignee=145&state=closed

In the example above, the cases are filtered to those which are assigned to 145 AND whose state is closed.

GET /cases/?state=in_progress,closed

In the example above, the cases filter will return all cases whose state is in_progress OR closed

All filters by default are inclusive. If a value is prefixed with an exclamation point (!) it will be treated as exclusive.

GET /cases/?state=!closed

In the example above, the cases filter will return all cases whose state is not closed.

By attribute on sub-object
If you want to check a field on a sub-object (e.g., products under customers) then we can use dot notation in the url parameters. For example:

GET /customers/?product.type=CRYPTO

By range

If you want to test a range, you can use explicit parameters and inequality characters. For example,

GET /cases/?created_at_from=2021-01-01&created_at_to=2023-01-01

Note:

  • The lower bound must end in the suffix _from.
  • The upper bound must end in the suffix _to.
  • The range must always be inclusive of both the lower and upper bounds.

String fields

When a field is a string, such as customer name, you can use name=john doe to mean exact match on the string field.

You can also use a parameter name_contains=john to do substring exact match.

Sorting

Sorting of lists must be explicitly defined by default, such that a list response is deterministic. If required, specific sorting can be specified via url parameters using the sort parameter specifying a comma separated set of sort fields in order of precedence. Default is sorting by ascending and you must include “-” explicitly for descending.

sort={optional -}{fieldName1},{optional -}{fieldName2},...

Example:

sort=assignee,-created_at.

This will sort first by assignee ascendingly, and then by created_at descendingly (most recently created ones come first).