Create Project

This endpoint creates a project and its default task, and returns the generated project ID.

Endpoint

POST /v1/projects/projects

Authentication

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

Required Scope

projects:write

Request Body

The server does not validate the request body before it writes to the database. If a required field is missing or has the wrong type, the API returns 500.

Field	Type	Required	Description
clientId	string	Yes	Parent client ID. A missing or unknown ID returns 500.
name	string	Yes	Project name. A missing name returns 500.
description	string | null	No	Project description. Defaults to null.
endCustomerId	string | null	No	Related end customer ID. Defaults to null. The API does not check that the end customer belongs to the same client. An unknown ID returns 500.
isArchived	boolean	No	Archive state. Defaults to false.
completed	boolean	No	Completion state. Defaults to false.
autoAssign	boolean	No	Auto-assign state. Defaults to false. When true, new users are assigned this project and its default task.
billingCategory	"BILLABLE" | "NON_BILLABLE" | null	No	Billing category. Defaults to null (not assigned). When set, the value applies to all of the project’s tasks, and tasks cannot set their own category. Any other string returns 500.
customFields	Record<string, string>	No	Custom fields. Defaults to {}.

Example Request Body

{
  "clientId": "client-ghi123jkl4567890",
  "name": "Project Name",
  "description": "A brief description of the project",
  "endCustomerId": "endcustomer-abc123def4567890",
  "isArchived": false,
  "completed": false,
  "autoAssign": true,
  "billingCategory": "BILLABLE",
  "customFields": {
    "department": "Operations"
  }
}

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/projects/projects" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client-ghi123jkl4567890",
    "name": "Project Name",
    "description": "A brief description of the project",
    "endCustomerId": "endcustomer-abc123def4567890",
    "isArchived": false,
    "completed": false,
    "autoAssign": true,
    "billingCategory": "BILLABLE",
    "customFields": {
      "department": "Operations"
    }
  }'

JavaScript

const response = await fetch("https://api.crewsum.com/v1/projects/projects", {
  method: "POST",
  headers: {
    "x-api-key": process.env.CREWSUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    clientId: "client-ghi123jkl4567890",
    name: "Project Name",
    description: "A brief description of the project",
    endCustomerId: "endcustomer-abc123def4567890",
    isArchived: false,
    completed: false,
    autoAssign: true,
    billingCategory: "BILLABLE",
    customFields: {
      department: "Operations",
    },
  }),
});
const result = await response.json();

HTTP

POST /v1/projects/projects HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "clientId": "client-ghi123jkl4567890",
  "name": "Project Name",
  "description": "A brief description of the project",
  "endCustomerId": "endcustomer-abc123def4567890",
  "isArchived": false,
  "completed": false,
  "autoAssign": true,
  "billingCategory": "BILLABLE",
  "customFields": {
    "department": "Operations"
  }
}

Response

On success, the API returns HTTP 201 Created.

Example Response

{
  "message": "Successfully created project",
  "data": {
    "projectId": "project-mno123pqr4567890"
  }
}

Behavior

• The API generates the project ID in the format project-<16 hex characters>.
• The API also creates a default task for the project. The default task has the same name as the project, the description Default task for: <project name>, isDefault: true, and the project’s billingCategory and autoAssign values. The default task is not archived, even when you create the project with isArchived: true.
• After the project is created, Crewsum emits the projects.created webhook event. A webhook delivery failure does not change the API response.

Error Responses

Status	Meaning
500	Crewsum could not create the project. The message is Error creating project. This includes a missing or unknown clientId, a missing name, an unknown endCustomerId, and an invalid billingCategory.

Authentication and scope failures are described in Errors.

Related Webhooks

projects.created View webhook event details.