Create End Customer

This endpoint creates an end customer and returns the generated end customer ID.

Endpoint

POST /v1/end-customers/end-customers

Authentication

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

Required Scope

end-customers: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	End customer name. When omitted, the request fails with `500`.
`description`	`string \| null`	No	End customer description. Defaults to `null`.
`clientId`	`string \| null`	No	Client to link the end customer to. Defaults to `null`. A client that does not exist in your account, or is deleted, returns `400`.
`email`	`string \| null`	No	End customer email. Defaults to `null`. The format is not checked.
`phoneNumber`	`string \| null`	No	End customer phone number. Defaults to `null`.
`address`	`string \| null`	No	End customer address. Defaults to `null`.
`notes`	`string \| null`	No	Internal notes. Defaults to `null`.
`isArchived`	`boolean`	No	Creates the end customer in an archived state when `true`. Defaults to `false`.

Example Request Body

{
  "name": "End Customer Name",
  "clientId": "client-ghi123jkl4567890",
  "email": "buyer@example.com",
  "phoneNumber": "555-0100",
  "address": "123 Main St"
}

Example Request

curl -X POST "https://api.crewsum.com/v1/end-customers/end-customers" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "End Customer Name",
    "clientId": "client-ghi123jkl4567890",
    "email": "buyer@example.com",
    "phoneNumber": "555-0100",
    "address": "123 Main St"
  }'

const response = await fetch(
  "https://api.crewsum.com/v1/end-customers/end-customers",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "End Customer Name",
      clientId: "client-ghi123jkl4567890",
      email: "buyer@example.com",
      phoneNumber: "555-0100",
      address: "123 Main St",
    }),
  },
);
const result = await response.json();

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

{
  "name": "End Customer Name",
  "clientId": "client-ghi123jkl4567890",
  "email": "buyer@example.com",
  "phoneNumber": "555-0100",
  "address": "123 Main St"
}

Response

On success, the API returns HTTP 201 Created.

Example Response

{
  "message": "Successfully created end customer",
  "data": {
    "endCustomerId": "endcustomer-abc123def4567890"
  }
}

Behavior

The API generates the end customer ID in the format endcustomer-<16 hex characters>.
Omitted optional fields are stored as null. isArchived defaults to false.
The new end customer has updatedAt: null until it is first updated.
After the end customer is created, Crewsum attempts to send the end-customers.created webhook event. A webhook failure does not change the response.

Error Responses

Status	Meaning
`400`	`{"message": "Client not found"}`. No client with this `clientId` exists in your account, or the client is deleted. Nothing is created.
`500`	`{"message": "Error creating end customer"}`. Crewsum could not create the end customer. 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.

end-customers.created View webhook event details.