Pagination

Overview

Any data you interact with via the Merge API is able to be paginated. Pagination is specified via the cursor and page_size query parameters. The next and previous cursors are attached to paginated API responses. Their values inform the cursor where to point to next.

Query Parameters

cursorString

Optional

Denotes the starting position in the data list from where a paginated API endpoint should return bulk data. Get this value from the next or previous property of any previous paginated response. When next or previous is null there are no more pages to paginate through.

page_sizeInteger

Optional

Limit on number of objects to return per request. Defaults to 30, maximum of 100.

Sample HTTP Request

Below is an sample request using pagination in HTTP. The page_size is set to 20, and the cursor is pointing to a value for the next page.



GET /api/ats/v1/candidates?page_size=20&cursor=cD0yMDIxLTA3LTI4KzE5JTNBMzglM0EzNi42NzUxNTMlMkIwMCUzQTAw 
Host: api.merge.dev
X-Account-Token: {Linked Account Token Here}
Authorization: Bearer {Production API Key Here}

Getting the Cursor

In the response payload of an API request to a paginated endpoint, you can find next and previous cursors.

Paginated API Response Payload

JSON


{
  "next": "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw",
  "previous": null,
  "results": [
      {...},
      {...},
      {...}
  ]
}

Using the Cursor

These cursors can be attached to future requests to paginated API endpoints to query the next (or previous) page of results, as demonstrated in the following code sample using the Merge SDK:

Paginating via Merge SDK


1# See SDK docs for configuration information
2api_client = MergeHRISClient.ApiClient(configuration)
3api_instance = MergeHRISClient.EmployeesApi(api_client)
4x_account_token = 'END_USER_ACCOUNT_TOKEN'
5cursor = ''
6
7while cursor != None:
8    try:
9        api_response = api_instance.employees_list(x_account_token, cursor)
10        pprint(api_response)
11        cursor = api_response.next
12    except MergeHRISClient.ApiException as e:
13        print('Exception when calling EmployeesApi->employees_list: %s' % e)

If you don't want to use the Merge SDK and want to form your own API requests instead, you can do so as illustrated below:

Paginating via Manual API Request


1import requests
2
3endpoint_url = "https://api.merge.dev/api/hris/v1/companies"
4
5headers = {"Accept": "application/json", "Authorization": "Bearer YOUR_API_KEY", "X-Account-Token": "END_USER_ACCOUNT_TOKEN"}
6response = requests.request("GET", endpoint_url, headers=headers)
7print(response.json()["results"])
8cursor = response.json()["next"]
9
10while cursor:
11    page_url = f"{endpoint_url}?cursor={cursor}"
12    response = requests.request("GET", page_url, headers=headers)
13    print(response.json()["results"])
14    cursor = response.json()["next"]