Paging Results

All API requests that return lists have paginated responses. By default, 50 items are returned and pagination _links are included for navigation between pages of results.

Auxiliary fields such as count, total, page and per_page are also included in the response body as properties that can be used to parse the results.

📘

Pagination on the client must be implemented by issuing a GET request to the next link, as long as one is included in the responses. Once the last page is reached, no next link will be included. To ease navigation, links to previous, first or last links can also be included.

Sample Response

{
  "total": 2,
  "page": 1,
  "per_page": 1,
  "_embedded": {
    "users": [
      {
        "id": "c65186ee-3780-468e-968b-ca15b981c312",
        "email": "[email protected]",
        "name": "John Smith",
        "active": true,
        "gender": "Male",
        "extension": 123,
        "external_phone_number": "+18000000000",
        "created_at": "2016-06-14T16:23:07Z",
        "_links": {
          "self": {
            "href": "https://api.talkdeskapp.com/users/{user_id}"
          },
          "account": {
            "href": "https://api.talkdeskapp.com/account"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.talkdeskapp.com/users"
    },
    "account": {
      "href": "https://api.talkdeskapp.com/account"
    },
    "next": {
      "href": "https://api.talkdeskapp.com/users?page=2"
    }
  }
}

🚧

Relying on Hypermedia Links

The page and per_page parameters used to identify the current page and number of results per page are just a default.

Other methods of pagination can be used for specific endpoints, and for this reason, a customer must not depend on these specific parameters as other forms of pagination may suit the use case better (e.g.: cursors for large quantities of data).

Talkdesk® recommends primarily relying on the hypermedia links information, as it will always be supported, and it encodes the specific pagination mechanism in use for the endpoint.

📘

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.