# Pagination
The Employee/OU API's GET endpoints segment large results of data into pages. You can control the page size, i.e. the number of records per page through the pageSize query parameter. For example, pageSize=5 indicates that you want Cornerstone to return five records per page.
If the pageSize query parameter is not included in your request, Cornerstone uses a default page size which varies based on the endpoint you are calling:
- Employee endpoints: 50 records per page
- OU endpoints: 100 records per page
When the following condition is met:
- total record count > pageSize,
the service will inject into the page response an encoded string named nextPageToken that is used to retrieve the next page of results. The nextPageToken has a time to live (TTL) of 5 minutes. The 5 minutes are calculated from the time of the API response. The nextPageToken should be treated as opaque, thus manipulating it in any way will result in incorrect results or errors.
# Employee Endpoints
Typically, you will want a list of employees from your portal. Since there are usually a large number of employees in any given portal, this will require pagination:
- Request the first page of the list of employees
- Request the second page of the list of employees if the end has not been reached
The examples below walk you through the two steps for the GET employees endpoint.
# Step 1: Request all users with a pageSize=2**
GET /services/api/x/users/v2/employees?pageSize=2
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
This will return the first two of all of your employees:
{
"timestamp": "2020-01-01T03:30:12.9545447Z",
"nextpagetoken": "t3ueLenNQeeyyrQARio0uaIlm596O4VwtLGcqhaEpno=",
"count": 2,
"data": [
{
"id": 1,
"externalId": "bsuser",
"userName": "CSODBSAdmin",
"guid": "e257f820-5a80-45cd-bf77-421d0bfedd68",
"firstName": "CSOD",
"lastName": "BusinessAdmin",
"middleName": null,
"prefix": null,
"suffix": null,
"primaryEmail": null,
"personalEmail": null,
"homePhone": null,
"mobilePhone": null,
"workPhone": null,
"fax": null,
"address": {
"country": "USA",
"line1": null,
"line2": null,
"city": null,
"state": null,
"zipCode": null
},
"workerStatus": {
"lastHireDate": null,
"originalHireDate": null,
"active": true,
"absent": false
},
"settings": {
"displayLanguage": "en-US",
"timeZone": "(UTC-08:00) Pacific Time (US & Canada)",
"trainingApprovals": 0
},
"managerId": null,
"approverId": 0,
"employeeMetaData": {
"createdDate": "2016-11-29T10:42:16.673",
"modifiedDate": null
}
},
{
"id": 2,
"externalId": "exampleUser1",
"userName": "exampleUser1",
"guid": "2eca8706-e070-4bfd-b8be-0972234354ab",
"firstName": "Example",
"lastName": "User1",
"middleName": null,
"prefix": null,
"suffix": null,
"primaryEmail": "exampleUser1@csod.com",
"personalEmail": null,
"homePhone": null,
"mobilePhone": null,
"workPhone": null,
"fax": null,
"address": {
"country": null,
"line1": null,
"line2": null,
"city": null,
"state": null,
"zipCode": null
},
"workerStatus": {
"lastHireDate": null,
"originalHireDate": null,
"active": true,
"absent": false
},
"settings": {
"displayLanguage": null,
"timeZone": null,
"trainingApprovals": 0
},
"managerId": null,
"approverId": null,
"employeeMetaData": {
"createdDate": "2005-08-10T16:56:59.81",
"modifiedDate": "2019-07-05T08:48:54.41"
}
}
]
}
# Step 2: Request page 2 of results
To retrieve the next set of records, you must add the nextPageToken query parameter to the next request. The value of the query parameter will be the encoded string value returned in the body of the previous response.
GET /services/api/x/users/v2/employees?nextPageToken=t3ueLenNQeeyyrQARio0uaIlm596O4VwtLGcqhaEpno=&pageSize=2
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
Essentially, the next request URL must be the same as the original URL with the addition of the nextPageToken query parameter and value.
This will return the next two sets of employee records. If you don't see a nextPageToken in the response body, that means the end of the results has been reached.
{
"timestamp": "2020-07-28T03:34:19.8152271Z",
"count": 2,
"data": [
{
"id": 3,
"externalId": "exampleAdmin1",
"userName": "exampleAdmin1",
"guid": "01705270-925a-40ed-9103-88c4bc40d27b",
"firstName": "Example",
"lastName": "Admin",
"middleName": null,
"prefix": null,
"suffix": null,
"primaryEmail": "exampleAdmin@csod.com",
"personalEmail": null,
"homePhone": null,
"mobilePhone": null,
"workPhone": null,
"fax": null,
"address": {
"country": null,
"line1": null,
"line2": null,
"city": null,
"state": null,
"zipCode": null
},
"workerStatus": {
"lastHireDate": null,
"originalHireDate": null,
"active": true,
"absent": false
},
"settings": {
"displayLanguage": null,
"timeZone": null,
"trainingApprovals": 0
},
"managerId": null,
"approverId": null,
"employeeMetaData": {
"createdDate": "2013-03-09T02:35:06.533",
"modifiedDate": null
}
},
{
"id": 4,
"externalId": "exampleUser2",
"userName": "exampleUser2",
"guid": "7a90f3d7-292d-4653-a919-5628c4f269bf",
"firstName": "Example",
"lastName": "User2",
"middleName": "",
"prefix": "",
"suffix": "",
"primaryEmail": "exampleUser2@csod.com",
"personalEmail": null,
"homePhone": null,
"mobilePhone": null,
"workPhone": "",
"fax": "",
"address": {
"country": null,
"line1": null,
"line2": null,
"city": null,
"state": null,
"zipCode": null
},
"workerStatus": {
"lastHireDate": null,
"originalHireDate": null,
"active": true,
"absent": false
},
"settings": {
"displayLanguage": null,
"timeZone": null,
"trainingApprovals": 0
},
"managerId": null,
"approverId": null,
"employeeMetaData": {
"createdDate": "2004-07-20T23:13:42.63",
"modifiedDate": null
}
}
]
}
# OU Endpoints
Typically, you will want a list of OUs from your portal. Since there are usually a large number of OUs in any given portal, this will require pagination:
- Request the first page of the list of OUs
- Request the second page of the list of OUs if the end has not been reached
The examples below walk you through the two steps for the GET OUs endpoint.
# Step 1: Request all Division OUs with pageSize=2
GET /services/api/x/organizations/v1/ous?typeId=2&pageSize=2
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
This will return the first two of all of your Division OUs:
{
"timestamp": "2020-01-01T18:40:29.6415916Z",
"pageNumber": 1,
"count": 2,
"data": [
{
"id": 10,
"active": true,
"name": "Example Division 1",
"externalId": "exampleDivision1",
"typeId": 2,
"ownerId": 1,
"description": "Example Division 1",
"parentId": 1,
"reconcilable": true
},
{
"id": 11,
"active": true,
"name": "Example Division 2",
"externalId": "exampleDivision2",
"typeId": 2,
"ownerId": 1,
"description": "Example Division 2",
"parentId": 1,
"reconcilable": false
}
],
"nextPageToken": "njv4280hQB5nd607ce4zQcSTl3ElyZCzF9BzgImDUB0="
}
# Step 2: Request page 2 of results
To retrieve the next set of records, you must add the nextPageToken query parameter to the next request. The value of the query parameter will be the encoded string value returned in the body of the previous response.
GET /services/api/x/organizations/v1/ous?typeId=2&pageSize=2&nextPageToken=njv4280hQB5nd607ce4zQcSTl3ElyZCzF9BzgImDUB0=
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
The next request URL must be the same as the original URL with the addition of the nextPageToken query parameter and value.
This will return the next two sets of Division OU records. If you don't see a nextPageToken in the response body, that means the end of the results has been reached.
{
"timestamp": "2020-01-01T18:45:24.1110777Z",
"pageNumber": 2,
"count": 2,
"data": [
{
"id": 12,
"active": true,
"name": "Example Division 3",
"externalId": "exampleDivision3",
"typeId": 2,
"ownerId": 1,
"description": "Example Division 3",
"parentId": 1,
"reconcilable": false
},
{
"id": 13,
"active": true,
"name": "Example Division 4",
"externalId": "exampleDivision4",
"typeId": 2,
"ownerId": 1,
"description": "Example Division 4",
"parentId": 1,
"reconcilable": false
}
]
}
# Incorrect Usage of nextPageToken
As stated before, the nextPageToken should be treated as opaque. You must not manipulate in any way. The following illustrates what occurs if the nextPageToken is manipulated.
# Step 1: Request all Division OUs with a pageSize = 2
GET /services/api/x/organizations/v1/ous?typeId=2&pageSize=2
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
This will return the first two of all of your divisions OUs:
{
"timestamp": "2020-01-01T18:40:29.6415916Z",
"pageNumber": 1,
"count": 2,
"data": [
{
"id": 10,
"active": true,
"name": "Example Division 1",
"externalId": "exampleDivision1",
"typeId": 2,
"ownerId": 1,
"description": "Example Division 1",
"parentId": 1,
"reconcilable": true
},
{
"id": 11,
"active": true,
"name": "Example Division 2",
"externalId": "exampleDivision2",
"typeId": 2,
"ownerId": 1,
"description": "Example Division 2",
"parentId": 1,
"reconcilable": false
}
],
"nextPageToken": "RA7/rzC/NImXLLXnegmwatG5q3g+1VoqJDQNkVqAl80="
}
# Step 2: Request page 2 of results with a manipulated nextPageToken
To retrieve the next set of records, the nextPageToken query parameter must be added to the next request. Let's say you modify the nextPageToken received in the previous response by removing the ending equals (=) sign and attempt to retrieve the next page.
GET /services/api/x/organizations/v1/ous?typeId=2&pageSize=2&nextPageToken=RA7/rzC/NImXLLXnegmwatG5q3g+1VoqJDQNkVqAl80
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
The API will respond with an 'invalid nextPageToken' error.
{
"timestamp": "2020-07-29T02:56:26.7049808Z",
"errorId": "75edb8b0-f6fc-499c-aaea-e5afec73ae35",
"error": {
"code": "INVALID_INPUT",
"message": "Validation Error",
"fields": [
{
"field": "nextPageToken",
"errors": {
"code": "400",
"message": "Invalid nextPageToken"
}
}
]
}
}