Most API endpoints have “list” API methods that allow you to retrieve a large set of data (e.g. list Activist Codes, list Survey Question, etc.). These endpoints share a common pattern for requests and responses.
Paginated endpoints accept the following optional parameters:
| Parameter | Location | Type | Description |
|---|---|---|---|
$top | query | int | A limit on the number of records to return in a single request, similar to a page size. This can be a value between 1 and the maximum $top value for a particular endpoint, typically 200. If no $top value is specified, an endpoint’s default $top size is used, typically 50. If an endpoint has a default $top but no maximum $top, you can retrieve all values by sending the $top parameter with no values (e.g., resources?$top=). The maximum and default values are documented for each endpoint. |
$skip | query | int | The number of records in a collection that should be skipped and not included in the result. If specified, must be greater than or equal to 0. For example, if you have a collection of 100 items and specify a $skip value of 10, the endpoint will return resources starting at 11. |
$expand | query | string | A comma-delimited list of expansion properties (see Expansion) |
$orderby | query | string | A comma-delimited list of properties and sort direction (asc or desc) to order results by before applying pagination filters. Defaults to asc. |
Paginated endpoints share a common response format as well. The endpoints will return an object with the following properties:
| Property | Type | Description |
|---|---|---|
items | array | An array of zero or more endpoint specific objects (e.g., an Activist Code) |
count | int | Total number of items available at this endpoint using the filters specified. This can be greater than the number of items in the items array. |
nextPageLink | string | An absolute URL at which additional records can be retrieved, if additional records are available. This will be the same as the request’s URL but with adjusted or appended $skip and $top values. |
If no results are returned, an HTTP Status Code 200 OK is returned with the items array empty, count property equal to 0, and the nextPageLink null:
{
"items": [],
"nextPageLink": null,
"count": 0
}