Customers API

Use the Customers API to create and manage customer records in a Cedius workspace.

Portfolio note: This is an illustrative API specification created for a technical-writing portfolio. The examples do not call a live production service.

Base path

text

/customers

All requests require:

http

Authorization: Bearer YOUR_API_KEY

Customer object

Field	Type	Description
`id`	string	Unique customer ID with the `cus_` prefix.
`name`	string	Customer or business name.
`email`	string \| null	Email address.
`phone`	string \| null	Phone number.
`company`	string \| null	Company name.
`address`	string \| null	Customer address.
`status`	string	`active` or `inactive`.
`notes`	string \| null	Internal notes.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 last-update timestamp.

json

{
  "id": "cus_4d7c21",
  "name": "Adewale Johnson",
  "email": "adewale@example.com",
  "phone": "+2348012345678",
  "company": "Johnson Ventures",
  "address": "12 Allen Avenue, Ikeja, Lagos",
  "status": "active",
  "notes": "Prefers bank transfer.",
  "created_at": "2026-09-09T11:12:40Z",
  "updated_at": "2026-09-09T11:12:40Z"
}

List customers

http

GET /customers

Returns customers in the authenticated workspace.

Query parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number. Default: `1`.
`limit`	integer	No	Records per page. Default: `20`; maximum: `100`.
`status`	string	No	Filter by `active` or `inactive`.
`search`	string	No	Search by name, email, or company.
`sort`	string	No	Sort field, such as `created_at`.
`order`	string	No	`asc` or `desc`.

Example request

bash

curl "https://api.cedius.app/v1/customers?status=active&page=1&limit=20" \
  -H "Authorization: Bearer cedius_test_sk_example"

Example response

200 OK

json

{
  "data": [
    {
      "id": "cus_4d7c21",
      "name": "Adewale Johnson",
      "email": "adewale@example.com",
      "phone": "+2348012345678",
      "company": "Johnson Ventures",
      "address": "12 Allen Avenue, Ikeja, Lagos",
      "status": "active",
      "notes": "Prefers bank transfer.",
      "created_at": "2026-09-09T11:12:40Z",
      "updated_at": "2026-09-09T11:12:40Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 86,
    "total_pages": 5
  }
}

Create a customer

http

POST /customers

Creates a customer in the authenticated workspace.

Request body

Field	Type	Required	Description
`name`	string	Yes	Name; 1–120 characters.
`email`	string	No	Valid email address.
`phone`	string	No	Maximum 30 characters.
`company`	string	No	Company name.
`address`	string	No	Customer address.
`notes`	string	No	Internal notes.

New customers are created with status: active.

Example request

bash

curl -X POST https://api.cedius.app/v1/customers \
  -H "Authorization: Bearer cedius_test_sk_example" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Adewale Johnson",
    "email": "adewale@example.com",
    "phone": "+2348012345678",
    "company": "Johnson Ventures"
  }'

Example response

201 Created

json

{
  "data": {
    "id": "cus_4d7c21",
    "name": "Adewale Johnson",
    "email": "adewale@example.com",
    "phone": "+2348012345678",
    "company": "Johnson Ventures",
    "address": null,
    "status": "active",
    "notes": null,
    "created_at": "2026-09-09T11:12:40Z",
    "updated_at": "2026-09-09T11:12:40Z"
  }
}

Validation error

422 Unprocessable Entity

json

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "email",
        "message": "Enter a valid email address."
      }
    ],
    "request_id": "req_71fa2c"
  }
}

Retrieve a customer

http

GET /customers/{customer_id}

Path parameter

Parameter	Type	Required	Description
`customer_id`	string	Yes	Customer ID beginning with `cus_`.

Example request

bash

curl https://api.cedius.app/v1/customers/cus_4d7c21 \
  -H "Authorization: Bearer cedius_test_sk_example"

Example response

200 OK

json

{
  "data": {
    "id": "cus_4d7c21",
    "name": "Adewale Johnson",
    "email": "adewale@example.com",
    "phone": "+2348012345678",
    "company": "Johnson Ventures",
    "address": "12 Allen Avenue, Ikeja, Lagos",
    "status": "active",
    "notes": "Prefers bank transfer.",
    "created_at": "2026-09-09T11:12:40Z",
    "updated_at": "2026-09-09T11:12:40Z"
  }
}

If the customer does not exist, return 404 Not Found with resource_not_found.

Update a customer

http

PATCH /customers/{customer_id}

Editable fields are name, email, phone, company, address, status, and notes. Omitted fields remain unchanged.

Example request

bash

curl -X PATCH https://api.cedius.app/v1/customers/cus_4d7c21 \
  -H "Authorization: Bearer cedius_test_sk_example" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+2348098765432",
    "notes": "Updated contact number."
  }'

Example response

200 OK

json

{
  "data": {
    "id": "cus_4d7c21",
    "name": "Adewale Johnson",
    "email": "adewale@example.com",
    "phone": "+2348098765432",
    "company": "Johnson Ventures",
    "address": "12 Allen Avenue, Ikeja, Lagos",
    "status": "active",
    "notes": "Updated contact number.",
    "created_at": "2026-09-09T11:12:40Z",
    "updated_at": "2026-09-09T15:42:10Z"
  }
}

Delete a customer

http

DELETE /customers/{customer_id}

Deletes a customer only when no blocking financial records are associated with that customer. Customers with invoice or payment history should normally be marked inactive instead.

Example request

bash

curl -X DELETE https://api.cedius.app/v1/customers/cus_4d7c21 \
  -H "Authorization: Bearer cedius_test_sk_example"

Successful response

204 No Content

A successful deletion returns no response body.

If financial records block deletion, return 409 Conflict:

json

{
  "error": {
    "code": "conflict",
    "message": "This customer cannot be deleted because financial records are associated with the customer. Mark the customer as inactive instead.",
    "request_id": "req_b184c2"
  }
}

Common errors

Status	Code	Meaning
`401`	`authentication_failed`	API key is missing or invalid.
`403`	`permission_denied`	The authenticated identity cannot perform the action.
`404`	`resource_not_found`	Customer does not exist.
`409`	`conflict`	Operation conflicts with the customer's current state.
`422`	`validation_error`	One or more submitted values are invalid.
`429`	`rate_limit_exceeded`	Request limit has been exceeded.

Validation rules

Field	Rule
`name`	Required on creation; 1–120 characters.
`email`	Must be a valid email when provided.
`phone`	Maximum 30 characters when provided.
`status`	Must be `active` or `inactive`.

Customers API ​

Base path ​

Customer object ​

List customers ​

Query parameters ​

Example request ​

Example response ​

Create a customer ​

Request body ​

Example request ​

Example response ​

Validation error ​

Retrieve a customer ​

Path parameter ​

Example request ​

Example response ​

Update a customer ​

Example request ​

Example response ​

Delete a customer ​

Example request ​

Successful response ​

Common errors ​

Validation rules ​

Related documentation ​

Customers API

Base path

Customer object

List customers

Query parameters

Example request

Example response

Create a customer

Request body

Example request

Example response

Validation error

Retrieve a customer

Path parameter

Example request

Example response

Update a customer

Example request

Example response

Delete a customer

Example request

Successful response

Common errors

Validation rules

Related documentation