Pagination

All pagination related query parameters begin with page.

List endpoints

List endpoints typically limit the number of entities returned. This is considered a “page” of results. There is a meta root property in the response, containing pagination metadata;

{
	"contacts": [...],
	"meta": {
		"page": {
			"pageOffset": 0,
			"pageSize": 20,
			"count": 11394
		}	
	}
}

count is the total number of entities.

pageSize is the max number of items per page. This can be changed by passing the pageSize query parameter; e.g. pageSize=35.

pageOffset is where the page starts from, i.e. the index position of the first item to return from the overall result set. This is 0 by default. If you would like further pages, pass the pageOffset query parameter; e.g. pageOffset=20.

Implementation

Let’s look at an example of how use these paging parameters. Let’s use the contacts endpoint in this example.

To return all contacts, paging is necessary. This is documented in the API reference, it allows you to pass in paging parameters.

  • The pageSize parameter defines the number of entities to want to be returned in a single page. Eg. pageSize=50, will ensure 50 contacts are returned.
  • The pageOffset is the index, always starting or defaulting to 0 on the first call.

To use these paging parameters, you simply add them to the path using query parameters:

https://{teamworkURL}/crm/api/v2/contacts.json?&pageSize=50&pageOffset=0

This will return the first 50 contacts. In your response you will see a meta object, this contains all you need to know for returning the second page:

{
	"contacts": [...],
	"meta": {
		"page": {
			"pageOffset": 0,
			"pageSize": 50,
			"count": 150
		}	
	}
}

You’ll see from this response, there is:

  • pageSize=50 returns 50 records at one time.
  • pageOffset is 0 because it’s the first page, defaulted to 0. To return the next page, the index must be increased by the amount of records it has returned. If page 2 is to tbe returned next, pass in a pageOffset of 50.
  • count is the total count of contacts being 150 in this case.

In this case, to get page 2 of contacts, and return records 51-100, the call would be:
https://{teamworkURL}/crm/api/v2/contacts.json?&pageSize=50&pageOffset=50

To get page 3 and return records 101-150, the call would be:

https://{teamworkURL}/crm/api/v2/contacts.json?&pageSize=50&pageOffset=150

To-many relationships

Some endpoints (single entity and list endpoints) support pagination for to-many relationships. An example query parameter would be like pageSize[contacts]=15 where contacts is the relationship name. Check the endpoint’s documentation to see if this is supported.

It’s not possible to change the offset to get further pages in this case; you’ll need to use another endpoint to get what you want.

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.