Make Your First Request

This guide calls List Clients to read the first page of clients in your Crewsum account.

Before you start

You need an API key with the clients:read scope. See Create an API Key.

Send the request

1. Store your API key in an environment variable, so that it does not appear in your code or shell history:

   export CREWSUM_API_KEY="<your-api-key>"

2. Send a GET request to /v1/clients/clients with the key in the x-api-key header. This example asks for the first 5 clients, sorted by name.

   cURL

   curl "https://api.crewsum.com/v1/clients/clients?page=0&pageSize=5&sortCol=clientName&sortDir=asc" \
     -H "x-api-key: $CREWSUM_API_KEY"

   JavaScript

   // Node.js 18 or later
   const url = new URL("https://api.crewsum.com/v1/clients/clients");
   url.search = new URLSearchParams({
     page: "0",
     pageSize: "5",
     sortCol: "clientName",
     sortDir: "asc",
   });
   
   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(`Crewsum API error ${response.status}: ${body.message}`);
   }
   
   for (const client of body.data.clients) {
     console.log(client.id, client.name);
   }
   console.log(`Total clients: ${body.data.count}`);

   Python

   # pip install requests
   import os
   import requests
   
   response = requests.get(
       "https://api.crewsum.com/v1/clients/clients",
       headers={"x-api-key": os.environ["CREWSUM_API_KEY"]},
       params={"page": 0, "pageSize": 5, "sortCol": "clientName", "sortDir": "asc"},
       timeout=30,
   )
   body = response.json()
   
   if not response.ok:
       raise RuntimeError(f"Crewsum API error {response.status_code}: {body['message']}")
   
   for client in body["data"]["clients"]:
       print(client["id"], client["name"])
   print(f"Total clients: {body['data']['count']}")

3. Check the response. A successful request returns HTTP 200 OK and a JSON body like this:

   {
     "message": "Successfully fetched clients",
     "data": {
       "clients": [
         {
           "id": "client-4b7f7fe08b294c1b",
           "name": "Harbor Health Systems",
           "description": "Hospital network, IT modernization",
           "isArchived": false,
           "createdAt": "2026-10-04T18:49:04.904Z",
           "updatedAt": null,
           "isDeleted": false,
           "customFields": {}
         },
         {
           "id": "client-1a0c5d2e9b7f4a3c",
           "name": "Northwind Logistics",
           "description": "Regional freight and warehousing",
           "isArchived": false,
           "createdAt": "2026-10-04T18:49:04.897Z",
           "updatedAt": null,
           "isDeleted": false,
           "customFields": {}
         }
       ],
       "count": 2
     }
   }

   • data.clients holds the clients on this page.
   • data.count is the total number of clients that match the request, across all pages.

   If your account has no clients yet, clients is an empty array and count is 0.

If the request fails

What you see	Likely cause
500 with "The x-api-key header missing or in an incorrect format"	The x-api-key header is missing. Check that the environment variable is set.
500 with "The provided api key was not found" or "...could not be validated"	The key is wrong, incomplete, or deleted.
500 with "Insufficient scopes, this endpoint requires the following scopes: clients:read"	The key does not have the clients:read scope.
500 with a subscription message	Your Crewsum account does not have an active subscription.
429	You sent more than 1,000 requests in one minute. Wait for the time in the retry-after header.

Errors describes every error response.

Next steps

• Read more pages of results with Pagination.
• Browse the endpoints in the API Reference.
• Get notified about changes with webhooks.