Create Supplier

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

Endpoint

POST /v1/suppliers/suppliers

Authentication

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

Required Scope

suppliers:write

Request Body

Field	Type	Required	Description
name	string	Yes	Supplier name. If it is missing, the API returns 500.
description	string	No	Supplier description. Stored as null when omitted.

Example Request Body

{
  "name": "Supplier Name",
  "description": "A brief description of the supplier"
}

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/suppliers/suppliers" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Supplier Name",
    "description": "A brief description of the supplier"
  }'

JavaScript

const response = await fetch("https://api.crewsum.com/v1/suppliers/suppliers", {
  method: "POST",
  headers: {
    "x-api-key": process.env.CREWSUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Supplier Name",
    description: "A brief description of the supplier",
  }),
});
const result = await response.json();

HTTP

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

{
  "name": "Supplier Name",
  "description": "A brief description of the supplier"
}

Response

On success, the API returns HTTP 201 Created.

Example Response

{
  "message": "Successfully created supplier: supplier-stu123vwx4567890",
  "data": {
    "supplierId": "supplier-stu123vwx4567890"
  }
}

Behavior

• The API generates the supplier ID in the format supplier-<16 hex characters>.
• New suppliers are active (isArchived: false) and have updatedAt: null.
• The request body is not validated against a schema. Wrong types are stored as sent or cause a 500.
• After the supplier is created, Crewsum sends the suppliers.created webhook event. The payload is { "suppliers": [<supplier>] }.

Error Responses

Status	Meaning
500	Crewsum could not create the supplier, for example because name was missing. Message: Error creating supplier. If no request body is sent, the API returns a 500 with a generic error body instead.

Authentication and scope failures are described in Errors.

Related Webhooks

suppliers.created View webhook event details.