Skip to main content

Filtering, Paging, Sorting

Sorting​

Endpoints that support sorting will have sort_by and sort_direction documented. sort_by is used to indicate the field to sort on, and all options are listed on a case-by-case basis, including the default. sort_direction is used to indicate the direction of the sort. The valid options are documented on a case-by-case basis, but will be ASC and DESC. When sorting ASC, null values will be sorted first. When sorting DESC, null values will be sorted last.

In the response metadata, the sort_by and sort_direction values will be provided back. This value will include the null ordering as well as the sort that was used.

If a sort is invalid, a 422 will be returned with an error indicating that the sort is invalid. If you see this, check that the sort provided is correct against the allowed values in the documentation.

Paging​

Endpoints that support paging will have per_page and page documented. per_page is how many records will be returned in a single request. This number will generally default to 25 and be in the inclusive range [1, 100]. The default and range is documented on each endpoint. page is the current index of the result set. The minimum page is 1, not 0, and there is no maximum value. However, requesting high page numbers will result in an increased rate limiting cost (see Rate Limits section for additional information). If you request a page with no results on it, your results will be empty.

In the response metadata, the per_page and page values will be provided back as per_page and current_page respectively. There are other values provided that are documented below.

{
  "per_page": "value of per_page",
  "current_page": "value of page",
  "next_page": "value of the next valid page, or null",
  "prev_page": "value of the previous valid page, or null",
  "total_pages": "count of the total number of pages",
  "total_count": "count of the total number of records for this request"
}

If per_page is outside of the allowed range or page is not valid, these values will be corrected to default values and provided in the response metadata.

Filtering​

Filters are provided on a per-endpoint basis, and will be documented on endpoints that support filters. In the response metadata, the filter name and value will be provided back.

Invalid filter names will be ignored as they are not valid query parameters. Invalid values can result in a 422 with a descriptive errors field returned.

Case insensitive partial matching can be accomplished for supported filters. Filters that support partial matching will indicate so via "Supports partial matching". Partial matching requires at least 3 characters that the value starts with. The param that is passed is an object with a key of "_starts_with" and the value being the value that you wish to partially match on.

Example: ?industry[_starts_with]=Health