Pagination

Paginating through resources

Most key resources in SmartAPIs support for bulk fetches and return the result data in lists. For example, you can list candidates, list jobs, list reviews and list users. Each time you make an API call to these endpoints, the data returned to you are not a complete full list but rather a portion of the list.

SmartRecruiters utilizes cursor-based pagination approach to return large collection data in a more resource efficient manner.

🚧

Other Pagination Methods

SmartRecruiters is gradually moving all APIs that support pagination to use the cursor-based approach. However, you may still find some endpoints using a different pagination technique and those respective individual documents should be your source of truth for which pagination approach for the endpoint to use.

Keep in mind a cursor-paginated call returns two things:

  1. A portion of the collection you are querying for and
  2. A cursor that points to the next portion of the collection. In SmartRecruiters case, this cursor is the nextPageId parameter. In some cases, it is the next parameter of the Link object returned in the header.

Example

To provide a more concrete example on how cursor-based pagination works, let's consider ListUsers endpoint.

We can make a call to list all users in the SmartRecruiters account, where we set the limit=5 to limit the number of users to be returned on the first "page" to 5

curl --request GET \
     --url 'https://api.smartrecruiters.com/user-api/v201804/users?limit=5' \
     --header 'Accept: application/json' \
     --header 'x-smarttoken: DCRA1-d0b1128084f*********************'

In return, we obtain our list of users with 5 results. And you will also notice the nextPageId property included in the returned list.

{
"limit":5
"nextPageId":"5fc4c5aa357d700efe2215ab"
"content":[
{
"id":"60f818625414a64b384c8705"
"firstName":"Gabriel"
"lastName":"Lira"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2021-07-22T09:31:59.134Z"
"language":{
"code":"en"
}
"ssoLoginMode":"PASSWORD"
}
{
"id":"6086ef05e26a732d0ac22157"
"firstName":"Dane"
"lastName":"Wesolko"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2021-04-26T16:50:25.761Z"
"language":{
"code":"en"
}
"ssoLoginMode":"PASSWORD"
}
{
"id":"60660ebda7b4fc2dd2538aa0"
"firstName":"Paweł"
"lastName":"Łoziński"
"email":"[email protected]"
"active":false
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2021-04-01T18:19:41.378Z"
"language":{
"code":"en"
}
"ssoLoginMode":"PASSWORD"
}
{
"id":"600eff1749e3995763c19d18"
"firstName":"Natalie"
"lastName":"Test"
"email":"[email protected]"
"active":false
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2021-01-25T17:25:43.335Z"
"language":{
"code":"en"
}
"ssoLoginMode":"PASSWORD"
}
{
"id":"5fc4c5aa357d700efe2215ab"
"firstName":"Balazs"
"lastName":"Admin"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2020-11-30T10:13:25.384Z"
"language":{
"code":"en"
}
"ssoLoginMode":"SSO"
}
]
}

nextPageId is the cursor pointing at the next page of result. To retrieve the next collection, simply include the value of nextPageId in your next query.

curl --request GET \
     --url 'https://api.smartrecruiters.com/user-api/v201804/users?limit=5&pageId=5fc4c5aa357d700efe2215ab' \
     --header 'Accept: application/json' \
     --header 'x-smarttoken: DCRA1-d0b1128084f********************'

And you will see your next page result.

{
"limit":5
"nextPageId":"5edecbd30beb9f4569e48d5a"
"content":[
{
"id":"5f736bed93b79d05487e7c46"
"firstName":"Arun"
"lastName":"Hari"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2020-09-30T08:20:26.739Z"
"language":{
"code":"en"
}
}
{
"id":"5f343b6680bd5d0eae9e43c6"
"firstName":"Connie"
"lastName":"Basic"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"RESTRICTED"
}
"updatedOn":"2020-10-01T22:54:22.131Z"
"language":{
"code":"en"
}
"accessGroups":[...]
}
{
"id":"5f32c6ae3f4eff0713727b6e"
"firstName":"Gabriel"
"lastName":"Lira"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2020-09-17T09:54:19.234Z"
"language":{
"code":"en"
}
}
{
"id":"5f1ea3789702a464e3a4f05f"
"firstName":"Katy"
"lastName":"Osborn"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"ADMINISTRATOR"
}
"updatedOn":"2020-07-27T09:52:23.118Z"
"language":{
"code":"en"
}
}
{
"id":"5edecbd30beb9f4569e48d5a"
"firstName":"Connie"
"lastName":"Standard"
"email":"[email protected]"
"active":true
"systemRole":{
"id":"a9d35fb1-453f-4cc6-a72e-86c4417a5eb3"
}
"updatedOn":"2021-07-23T22:35:44.676Z"
"language":{
"code":"en"
}
"ssoLoginMode":"SSO"
}
]
}

You can also adjust limit and other filters supported by the endpoint. If the remaining collection does not have the number of items you specified in your limit, as you may expect, the result will just contain the rest of the collection.