Pagination, Sorting, and Filters

Most list endpoints in the Crewsum customer API use the same query parameters for paging, sorting, and archived records. This page describes those shared rules. Each list endpoint page gives the exact parameters, sort columns, and filters that it supports.

All query parameter values are strings in the URL. The API converts them as described below.

Paging

Parameter	Default	Description
page	0	The page to return. The first page is 0, not 1.
pageSize	25	The number of items on each page. There is no maximum.

The API skips page × pageSize items and returns the next pageSize items.

Paged list responses contain the items for the current page and a count:

{
  "message": "Successfully fetched clients",
  "data": {
    "clients": [],
    "count": 3
  }
}

count is the total number of items that match your filters, across all pages. It is not the number of items on this page. The name of the item array depends on the endpoint, such as clients, projects, or users.

Read every page

Increase page until you have read count items, or until a page comes back empty.

cURL

curl "https://api.crewsum.com/v1/clients/clients?page=0&pageSize=100" \
  -H "x-api-key: $CREWSUM_API_KEY"
curl "https://api.crewsum.com/v1/clients/clients?page=1&pageSize=100" \
  -H "x-api-key: $CREWSUM_API_KEY"

JavaScript

async function listAllClients() {
  const pageSize = 100;
  const clients = [];

  for (let page = 0; ; page++) {
    const url = `https://api.crewsum.com/v1/clients/clients?page=${page}&pageSize=${pageSize}`;
    const response = await fetch(url, {
      headers: { "x-api-key": process.env.CREWSUM_API_KEY },
    });
    const body = await response.json();
    if (!response.ok) throw new Error(body.message);

    clients.push(...body.data.clients);
    if (body.data.clients.length === 0 || clients.length >= body.data.count) {
      return clients;
    }
  }
}

Python

import os
import requests

def list_all_clients():
    page_size = 100
    clients = []
    page = 0
    while True:
        response = requests.get(
            "https://api.crewsum.com/v1/clients/clients",
            headers={"x-api-key": os.environ["CREWSUM_API_KEY"]},
            params={"page": page, "pageSize": page_size},
            timeout=30,
        )
        body = response.json()
        response.raise_for_status()

        items = body["data"]["clients"]
        clients.extend(items)
        if not items or len(clients) >= body["data"]["count"]:
            return clients
        page += 1

Edge cases

• A page or pageSize value that is not a number, such as pageSize=all, is ignored, and the default is used.
• pageSize=0 returns an empty page. count is still the total.
• A negative page or pageSize can cause an error (500).
• A page after the last page returns an empty array. count is still the total.
• Records can be added or changed while you page through a list. If you need a stable order, sort by createdAt.

Sorting

Parameter	Description
sortCol	The field to sort by. Each list endpoint page lists the allowed values.
sortDir	asc or desc.

The API uses sortCol and sortDir only when you send both, and both values are valid. If either one is missing or invalid, the API ignores both without an error and uses the default order.

For most list endpoints:

• sortDir is not case-sensitive (ASC works).
• The default order is updatedAt descending, then createdAt descending. Records that were never updated (updatedAt: null) come last.
• Empty (null) values come last in both directions.

List Timesheets has different rules: sortCol is one of submitted_at, period_start, or period_end, sortDir must be lowercase, and the default order is by submitted_at, newest first.

curl "https://api.crewsum.com/v1/projects/projects?sortCol=createdAt&sortDir=asc" \
  -H "x-api-key: $CREWSUM_API_KEY"

Archived records

Many list endpoints return only records that are not archived by default. Two parameters change this:

Parameter	Description
archived	true returns only archived records.
all	true returns archived and non-archived records. When all=true, the API ignores archived.

These parameters are true only for the exact value true (lowercase). Any other value, such as 1, yes, or True, is treated as false.

You send	You get
Nothing	Non-archived records
archived=true	Archived records only
all=true	All records

List endpoints do not return deleted records. The exception is List Tasks: with all=true, it also returns deleted tasks. Check isDeleted on each task.

Which endpoints use these rules

Endpoint	Paging	Sorting	archived and all
List Clients	Yes	Yes	Yes
List End Customers	Yes	Yes	Yes
List Projects	Yes	Yes	Yes
List Contacts	Yes	Yes	Yes
List Tasks	Yes	Yes	Yes
List Suppliers	Yes	Yes	Yes
List Supplier Contacts	Yes	Yes	Yes
List Users	Yes	Yes	Yes
List User Groups	Yes	Yes	No
List Timesheets	Yes	Yes, with different rules	No
List Associations	No, returns all matches	No	No
List User Assignments	No, returns all matches	No	No

Some list endpoints also have their own filters, such as clientId or projectId. See each endpoint page.