Pagination
Paginating through resources
Most key resources in SmartAPIs support bulk fetch 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 is not a complete full list but rather a portion of the list.
SmartRecruiters utilizes a 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:
- A portion of the collection you are querying for and
- A cursor that points to the next portion of the collection. In SmartRecruiters case, this cursor is the
nextPageIdparameter. In some cases, it is thenextparameter of theLinkobject returned in the header.
Example
To provide a more concrete example of how cursor-based pagination works, let's consider the 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 the SmartRecruiter'sresult. To retrieve the next collection, simply include the value of the 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 the 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.
Updated over 1 year ago