List Projects

This endpoint returns a page of projects for the authenticated account.

Endpoint

GET /v1/projects/projects

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

projects:read

Query Parameters

Parameter	Type	Required	Description
`clientId`	`string`	No	Return only projects for this client.
`billingCategory`	`"billable" \| "non-billable" \| "not-assigned"`	No	Filter by billing category. The values are lowercase. `not-assigned` matches projects with a `null` category. Any other value applies no filter.
`archived`	`string`	No	`"true"` returns only archived projects. Any other value, or no value, returns only non-archived projects.
`all`	`string`	No	`"true"` returns archived and non-archived projects and ignores `archived`.
`page`	`string`	No	0-based page index. Defaults to `0`.
`pageSize`	`string`	No	Number of items per page. Defaults to `25`.
`sortCol`	`string`	No	Sort column. One of `projectName`, `projectDescription`, `EndCustomer.name`, `createdAt`, `updatedAt`, `Client.client_name`.
`sortDir`	`string`	No	Sort direction: `asc` or `desc` (not case-sensitive).

The API uses sortCol and sortDir only when both are present and valid. Otherwise it ignores them without an error and sorts by updatedAt then createdAt, newest first. See Pagination for paging and sorting rules.

Request Body

This endpoint does not accept a request body.

Example Request

curl "https://api.crewsum.com/v1/projects/projects?clientId=client-ghi123jkl4567890&billingCategory=billable&page=0&pageSize=25" \
  -H "x-api-key: $CREWSUM_API_KEY"

const response = await fetch(
  "https://api.crewsum.com/v1/projects/projects?clientId=client-ghi123jkl4567890&billingCategory=billable&page=0&pageSize=25",
  {
    headers: { "x-api-key": process.env.CREWSUM_API_KEY },
  },
);
const result = await response.json();

GET /v1/projects/projects?clientId=client-ghi123jkl4567890&billingCategory=billable&page=0&pageSize=25 HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>

Response

On success, the API returns HTTP 200 OK.

Example Response

{
  "message": "Successfully fetched projects",
  "data": {
    "projects": [
      {
        "id": "project-mno123pqr4567890",
        "name": "Project Name",
        "description": "A brief description of the project",
        "endCustomerId": "endcustomer-abc123def4567890",
        "endCustomerName": "End Customer Name",
        "endCustomerDeleted": false,
        "endCustomerArchived": false,
        "isArchived": false,
        "createdAt": "2026-01-05T15:30:00.000Z",
        "updatedAt": "2026-01-12T09:15:00.000Z",
        "clientId": "client-ghi123jkl4567890",
        "clientName": "Client Name",
        "isDeleted": false,
        "clientDeleted": false,
        "clientArchived": false,
        "billingCategory": "BILLABLE",
        "completed": false,
        "autoAssign": true,
        "associations": [
          {
            "contactId": "contact-jkl123mno4567890",
            "contactName": "Contact Name",
            "contactEmail": "placeholder@example.com",
            "contactType": "MANAGER",
            "notificationLevel": "COPY_ONLY"
          }
        ],
        "customFields": {
          "department": "Operations"
        },
        "submittedHours": 40
      }
    ],
    "count": 1
  }
}

Behavior

count is the total number of matching projects across all pages.
Deleted projects are never returned.
List items have the same fields as Get Project, except clientCustomFields, which list items do not include.
submittedHours is the total of hours on approved timecards for the project.
hoursBudget is included only when the project has an hours budget.

Error Responses

Status	Meaning
`500`	Crewsum could not fetch projects. The message is `Error fetching projects`.

Authentication and scope failures are described in Errors.

This endpoint does not trigger a webhook.