Pagination

In this guide, we will look at how to work with paginated responses when querying the LSP.expert API.

All top-level API resources have support for bulk fetches through “list” API methods. For example, you can list jobs, list clients, and list invoices. These list API methods share a common structure and accept, at a minimum, the following parameters: page, sort, direction.

 

Search request format

  • pagenumber

    The page number to fetch. The first page is 1. If not provided, the default is 1.

  • sortstring

    The field to sort by. Each resource may support different sort options. If not provided, the default is the resource's default sort order.

  • directioninteger

    The direction to sort by: asc or desc. If not provided, the default is the resource's default sort direction.

Search response format

  • itemsarray

    The list of items.

  • pageSizenumber

    The number of items per page. It is set in the account settings (Advanced options, number of items per page) and cannot be changed in the request.

  • pagenumber

    The current page number.

  • totalPagesnumber

    The total number of pages.

  • totalItemsnumber

    The total number of items.

  • hasNextPageboolean

    Indicates whether there is a next page.

  • hasPreviousPageboolean

    Indicates whether there is a previous page.

Manual pagination using cURL

curl -G https://api.lsp.expert/v2/jobs \
  -u {key}: \
  -d page=2

Paginated response

{
  "items": [
    {
      "id": "WAz8eIbvDR60rouK",
      // ...
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    },
    {
      "id": "fbwYwpi9C2ybt6Yb"
      // ...
    }
  ],
  "pageSize":20,
  "page":2,
  "totalPages":10,
  "totalItems":198,
  "hasNextPage":true,
  "hasPreviousPage":true
}

Filtering and sorting

Most list endpoints also accept filters and a sort. Each list endpoint documents its own filters and the fields it can be sorted on, for example jobs, quotes or invoices. The rules below are shared by all of them.

Filters

  • Combining filters. All the filters are optional. When you provide several filters, only the items matching all of them are returned. Unknown filters are ignored.
  • Multiple values. Separate the values with commas in a single parameter, for example status=2,3 returns the items in status 2 or 3. Do not repeat the parameter: only a single value per parameter is read.
  • Ids. The filters on an entity (client.id, service.id...) take a comma-separated list of ids. An invalid id returns an error. The value null matches the items that have no value.
  • Text. A text filter (name, number...) returns the items that contain the text, whatever the case.
  • Numbers and currencies. A number filter such as total is an exact match. A currency filter takes an ISO code, for example EUR.
  • Booleans. Use true or 1. Any other value is read as false. A boolean filter such as archive returns both when it is not provided.
  • Dates. A date filter is split in two parameters: …From returns the items on or after the date and …To returns the items before the date. Use an ISO 8601 date, for example 2025-01-31 or 2025-01-31T09:00:00Z.
  • Current user. In a filter on users, me is replaced by the id of the authenticated user, for example user.id=me. It is not available on the list of outsourced jobs.
  • Labels. labels.id returns the items that have at least one of the labels. Add labels.all=true to return the items that have all of them. Clients and suppliers work the same way with users.all and domains.all.
  • Statuses. The status filters take the system statuses and the ids of custom statuses, mixed in the same list, for example status=1,2,6746a1b2c3d4e5f607182930.
  • Project managers. The projectManager.id filter takes a comma-separated list of user ids and returns the items of the clients managed by these users.
  • Access. The results are limited to the clients the authenticated user has access to, even if you filter on other clients.

Sorting

  • Use sort with one of the fields listed by the endpoint, and direction with asc or desc.
  • If sort is missing or is not one of the listed fields, the default sort of the endpoint is used. If direction is missing, the default direction of the endpoint is used.
  • Pinned items always come first, whatever the sort. Items with the same value are returned in a stable order, so a page never repeats or skips an item.

Filter and sort using cURL

curl -G https://api.lsp.expert/v2/jobs \
  -u {key}: \
  -d "status=2,3" \
  -d "client.id=6548c16d5136b418fd626e5f" \
  -d "dueDateTo=2025-02-01" \
  -d sort=dueDate \
  -d direction=asc