Clients

The Clients API exposes the same account/client aggregate used by the Woes Clients page. Client records are derived from workspace conversations, contacts, channels, and recent activity. The REST API can also create a manual client/account seed when another system needs a client to exist before the first customer conversation.

The REST Clients API does not expose workspace ids, raw conversation metadata, custom field internals, raw widget presence pages, provider details, or operator-only debug data.

Client Object

{
  "object": "client",
  "id": "example-api-co",
  "name": "Example API Co",
  "health": "watch",
  "healthScore": {
    "label": "watch",
    "score": 72,
    "activity": 85,
    "conversations": 66,
    "resolutions": 70,
    "reasons": ["1/4 conversations still open.", "75% resolution rate."]
  },
  "metrics": {
    "conversations": 4,
    "openConversations": 1,
    "messages": 38,
    "verifiedContacts": 2,
    "visits": 6
  },
  "channels": [
    { "channel": "live-chat", "count": 3 },
    { "channel": "email", "count": 1 }
  ],
  "contacts": [
    {
      "id": "cus_123",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "identitySource": "headers",
      "lastMessageAt": "2026-06-29T13:00:00.000Z",
      "online": false,
      "visits": 4
    }
  ],
  "recentConversations": [
    {
      "id": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33",
      "channel": "live-chat",
      "subject": "OAuth redirect URI mismatch",
      "preview": "Customer reports a redirect_uri mismatch.",
      "status": "open",
      "lastMessageAt": "2026-06-29T13:00:00.000Z"
    }
  ],
  "tasks": [
    {
      "id": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33",
      "subject": "OAuth redirect URI mismatch",
      "preview": "Customer reports a redirect_uri mismatch.",
      "status": "open",
      "priority": "High",
      "lastMessageAt": "2026-06-29T13:00:00.000Z"
    }
  ],
  "firstContactAt": "2026-06-20T16:00:00.000Z",
  "lastMessageAt": "2026-06-29T13:00:00.000Z",
  "latestConversationId": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33"
}

List Clients

GET /api/v1/clients

Query parameters:

Parameter	Type	Description
`limit`	number	1-100 clients. Default: `20`.
`search`	string	Matches client id, name, channels, or contacts.
`health`	string	`healthy`, `watch`, or `attention`.

curl "https://woes.dev/api/v1/clients?health=watch&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"

{
  "object": "list",
  "hasMore": false,
  "truncated": false,
  "clients": [
    {
      "object": "client",
      "id": "example-api-co",
      "name": "Example API Co",
      "health": "watch",
      "metrics": {
        "conversations": 4,
        "openConversations": 1,
        "messages": 38,
        "verifiedContacts": 2,
        "visits": 6
      }
    }
  ]
}

Create Client

POST /api/v1/clients

This creates a manual client seed as an API-origin support conversation. The client then appears in the same aggregate used by the Woes Clients page.

curl https://woes.dev/api/v1/clients \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Example API Co",
    "contactName": "Ada Lovelace",
    "contactEmail": "ada@example.com",
    "notes": "Created from CRM sync."
  }'

Create Client does not invite a user, open a customer portal session, send an email, or run automations. It seeds the client/account record for workspace visibility.

Retrieve Client

GET /api/v1/clients/{clientId}

Client ids are normalized from the customer company/account name on conversations. Use the id returned by GET /api/v1/clients.

curl https://woes.dev/api/v1/clients/example-api-co \
  -H "Authorization: Bearer $WOES_API_KEY"

If the client id is not present in the API key workspace, Woes returns 404.

Aggregation Window

Client records are built from the most recent workspace conversations. The response includes truncated: true when the workspace has more conversations than the current aggregation window, so integrations know older client activity may not be represented in the response.

Required Scopes

Endpoint	Scope
`GET /api/v1/clients`	`clients:read`
`POST /api/v1/clients`	`clients:write`
`GET /api/v1/clients/{clientId}`	`clients:read`

​Clients

​Client Object

​List Clients

​Create Client

​Retrieve Client

​Aggregation Window

​Required Scopes

Clients

Client Object

List Clients

Create Client

Retrieve Client

Aggregation Window

Required Scopes