Update Client

This endpoint updates an existing client by ID.

Endpoint

PUT /v1/clients/clients/:id

Authentication

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

Required Scope

clients:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Client ID to update.

Request Body

Send only the fields you want to change. Omitted fields keep their current values. The server does not validate the request body against a schema, so a value of the wrong type is not rejected with 400.

Field	Type	Required	Description
name	string	No	New client name. null is rejected by the database and returns 500.
description	string | null	No	New client description. Send null to clear it.
isArchived	boolean	No	New archive state.
customFields	Record<string, string>	No	Replaces the entire custom fields object. Send {} to remove all custom fields. Values are not validated, so send strings.

Example Request Body

{
  "description": "Updated description",
  "customFields": {
    "region": "west"
  }
}

Example Request

cURL

curl -X PUT "https://api.crewsum.com/v1/clients/clients/client-ghi123jkl4567890" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "customFields": {
      "region": "west"
    }
  }'

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/clients/clients/client-ghi123jkl4567890",
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "Updated description",
      customFields: {
        region: "west",
      },
    }),
  },
);
const result = await response.json();

HTTP

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

{
  "description": "Updated description",
  "customFields": {
    "region": "west"
  }
}

Response

On success, the API returns HTTP 200 OK. The response has no data field.

Example Response

{
  "message": "Successfully updated client: client-ghi123jkl4567890"
}

Behavior

• Every successful update sets updatedAt to the current time.
• Archiving a client does not archive its projects, contacts, or end customers.
• The API does not check that the client exists. An unknown ID returns 200 with the success message, nothing is changed, and no webhook is sent.
• After the client is updated, Crewsum attempts to send the clients.updated webhook event. A webhook failure does not change the response.

Error Responses

Status	Meaning
400	{"message": "ClientID missing"}. The ID path segment is empty.
500	{"message": "Error updating client: <id>"}. Crewsum could not update the client, for example because name is null.
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.updated View webhook event details.