Clients API

Client API access follows the current Keito permissions of the user bound to the credential. A full-access key does not make that user an Administrator.

Permissions

Identity	Read	Create and update	Archive, restore, delete
Owner or Administrator	All workspace clients	Yes	Yes
Manager with Edit clients and tasks	The same clients visible in Keito	Yes	No
Other active internal user	The same clients visible in Keito	No	No
Personal read-only sync key	List and item reads only	No	No

Role, Manager-permission, membership, and key-binding changes are checked on every request. External Client members cannot use a general API credential.

List Clients

GET /api/v2/clients

Supported query parameters are is_active, updated_since, page, and per_page.

curl "https://app.keito.ai/api/v2/clients?is_active=true&per_page=100" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

Get a Client

GET /api/v2/clients/{id}

A successful item read returns an ETag. Keep it if you may update or delete the client later.

Create a Client

POST /api/v2/clients

curl -X POST "https://app.keito.ai/api/v2/clients" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: client-create-001" \
  --data '{"name":"Example client","currency":"GBP","payment_terms":"net_30"}'

Create accepts name, address, currency, payment_terms, payment_days, tax, tax2, discount, and is_active. Custom payment terms require payment_days; other terms reject it. A successful create returns 201 Created, Location, and ETag.

Update, Archive, or Restore

PATCH /api/v2/clients/{id}

Send at least one writable property. Unknown and read-only properties are rejected. Use is_active: false to archive and is_active: true to restore; those status changes are Owner/Administrator-only.

curl -X PATCH "https://app.keito.ai/api/v2/clients/$CLIENT_ID" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "etag-from-the-latest-read"' \
  -H "Idempotency-Key: client-update-001" \
  --data '{"address":"1 Example Street"}'

If-Match is optional for PATCH but strongly recommended. A stale value returns 412 Precondition Failed. Archiving a client with active projects returns 409 Conflict.

Permanently Delete a Client

DELETE /api/v2/clients/{id}

Permanent deletion is Owner/Administrator-only. The client must already be archived, must have a current If-Match, and must have no blocking projects or financial documents. Otherwise Keito returns 409, 412, or 428 without deleting anything.

Use a disposable test client and archive it before testing deletion. Deletion cannot be undone.

Safe Retries and Request Rules

Mutation requests may include an Idempotency-Key containing 8–255 letters, numbers, dots, underscores, or hyphens. The same key, request, precondition, and authorization context replays the stored response for 24 hours. Reusing a key for different input, after a permission change, or while the original request is still running returns 409.

Bodies must be uncompressed UTF-8 application/json, are limited to 128 KiB, and use strict schemas. Responses are private, no-store.