Paginating Responses

Each API response is limited to a maximum of 1,000 records per request. To paginate through the entire result set, the API call can include the following optional request parameters for any API endpoints that return a collection of resources.

Note: If the request is for over 10,000 records, an asynchronous call is required.

Name Required? Type Description
limit No Integer Number of records to retrieve in the corresponding API call. The default (and maximum) value is 1,000.
offset No Integer Count by which to offset the API results. For example, a limit of 1,000 with an offset of 1,000 would retrieve the second block of 1,000 records. The default value is 0.

You can use these parameters as follows, for example:

  • To retrieve the first 100 contacts:

    GET /v1/contacts/?contactDbId=1&limit=100

  • To retrieve the second set of 500 contacts, skipping the first 500:

    GET /v1/contacts/?contactDbId=1&limit=500&offset=500

Contacts Search

The contacts search endpoint uses the concept of pages as opposed to offsetting a number of contacts. The request parameters are:

Name Required? Type Description
PageSize No Integer Number of records to retrieve in the corresponding API call. The default (and maximum) value is 1,000.
PageNumber No Integer The pageNumber to retrieve records from. The default value is 1.

You can use these parameters as follows, for example:

The PageSize value is set to 25 in the request:

{

"ContactDbId": 55,

"Filter": [

{

"FieldName": "FirstName",

"Value": ["Joe"],

"Operator": "Equals"

}],

"PageSize": 25,

"PageNumber": 1,

"VisibleFields": ["FirstName", "LastName", "Email", "School"]

}

In the response 104 contacts match the search criteria (this is shown in the contactsMatchingCriteria parameter)

"code": 200,

"message": "OK",

"searchMeta": {

"pageNumber": 1,

"pageSize": 25,

"contactsMatchingCriteria": 104,

"contactsOnPage": 25,

"totalContactsCount": 155468,

"numberOfPages": 5

},

 

Since the pageSize is 25 only the first 25 contacts will be returned in the initial request, this is the 1st page.

The remaining 79 contacts will be divided up into additional pages by the PageSize value i.e. in total there will be 5 pages (this is shown in the numberOfPages parameter).

These additional contacts can be retrieved by making additional requests and changing the PageNumber parameter to a valid value. If we want to retrieve the contacts on the 2nd page i.e. contacts 26-50 we change the PageNumber to 2 like figure 3.

{

"ContactDbId": 55,

"Filter": [

{

"FieldName": "FirstName",

"Value": ["Joe"],

"Operator": "Equals"

}],

"PageSize": 25,

"PageNumber": 2,

"VisibleFields": ["FirstName", "LastName", "Email", "School"]

}