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. Ensure that all query parameters, aside from cursor and page_size, remain consistent across pagination to maintain the integrity of your data retrieval. The next and previous cursors are attached to paginated API responses. Their values inform the cursor where to point to next.

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/candidates?page_size=20&cursor=cD0yMDIxLTA3LTI4KzE5JTNBMzglM0EzNi42NzUxNTMlMkIwMCUzQTAw 
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.

1
{
2
  "next": "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw",
3
  "previous": null,
4
  "results": [
5
      {...},
6
      {...},
7
      {...}
8
  ]
9
}

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:

1
# See SDK docs for configuration information
2
import merge
3
from merge.client import Merge
4
5
merge_client = Merge(api_key="<YOUR_API_KEY>", account_token="<YOUR_ACCOUNT_TOKEN>")
6
7
cursor = ""
8
9
while cursor != None:
10
    try:
11
        next_employees_page = merge_client.hris.employees.list(next=cursor)
12
        pprint(next_employees_page)
13
        cursor = next_employees_page.next
14
    except Exception as e:
15
        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:

1
import requests
2
3
endpoint_url = "https://api.merge.dev/api/hris/companies"
4
5
headers = {"Accept": "application/json", "Authorization": "Bearer YOUR_API_KEY", "X-Account-Token": "END_USER_ACCOUNT_TOKEN"}
6
response = requests.request("GET", endpoint_url, headers=headers)
7
print(response.json()["results"])
8
cursor = response.json()["next"]
9
10
while 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"]