Create Client

This endpoint creates a client and returns the generated client ID.

Endpoint

POST /v1/clients/clients

Authentication

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

Required Scope

clients:write

Request Body

The server does not validate the request body against a schema. A missing required field or a value of the wrong type is not rejected with 400. See the notes in each row.

Field	Type	Required	Description
name	string	Yes	The client name. When omitted, the request fails with 500.
description	string | null	No	A description for the client. Defaults to null.
isArchived	boolean	No	Creates the client in an archived state when true. Defaults to false.
customFields	Record<string, string>	No	Custom key-value metadata for the client. Defaults to {}. Values are not validated, so send strings.

Example Request Body

{
  "name": "Client Name",
  "description": "A brief description of the client",
  "isArchived": false,
  "customFields": {
    "region": "west",
    "accountManager": "Jordan Lee"
  }
}

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/clients/clients" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Name",
    "description": "A brief description of the client",
    "isArchived": false,
    "customFields": {
      "region": "west",
      "accountManager": "Jordan Lee"
    }
  }'

JavaScript

const response = await fetch("https://api.crewsum.com/v1/clients/clients", {
  method: "POST",
  headers: {
    "x-api-key": process.env.CREWSUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Client Name",
    description: "A brief description of the client",
    isArchived: false,
    customFields: {
      region: "west",
      accountManager: "Jordan Lee",
    },
  }),
});
const result = await response.json();

HTTP

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

{
  "name": "Client Name",
  "description": "A brief description of the client",
  "isArchived": false,
  "customFields": {
    "region": "west",
    "accountManager": "Jordan Lee"
  }
}

Response

On success, the API returns HTTP 201 Created.

Example Response

{
  "message": "Successfully created client: client-ghi123jkl4567890",
  "data": {
    "clientId": "client-ghi123jkl4567890"
  }
}

Behavior

• The API generates the client ID in the format client-<16 hex characters>.
• When description, isArchived, or customFields is omitted, the API uses null, false, or {}.
• The new client has updatedAt: null until it is first updated.
• After the client is created, Crewsum attempts to send the clients.created webhook event. A webhook failure does not change the response.

Error Responses

Status	Meaning
500	{"message": "Error creating client"}. Crewsum could not create the client. This is also the response when name is missing or a field has a value the database rejects.
500	The request has no JSON body. The response uses the standard server error shape.

Authentication and scope failures are described in Errors.

Related Webhooks

clients.created View webhook event details.