> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Operations

> Run the day-to-day settings of a workspace through the API: accounts, domains, numbers, buying, campaigns, leads, agents, inbox work, CRMs, billing reads, the team and agency clients.

## Overview

Similar things share one set of calls. A family has `GET` (list, or read one with `id`), `POST` (create), `PATCH /{id}` (change), `DELETE /{id}` and, where something happens rather than changes, `POST /{id}/actions`. A `type` field says which kind of thing you mean. The Sendora MCP has a matching action for each one, so an AI agent and your code use the same operations.

All calls send `X-API-Key`. Writes need a key with write access. Ids are the public ids the API returns; send them back as they are.

| Area | Calls |
| - | - |
| Lead lists, segments, stages, sources, requests | `/lead-collections` with `type` list, segment, stage, source or request |
| Work waiting on a person | `/work-items` with `type` approval, escalation, task or meeting (`view=attention` for the needs-attention list) |
| Sending accounts, domains, caller IDs, sender pools, CRMs, integration health, webhook endpoints, connected accounts, deliverability tests | `/connections` with `type` account, domain, caller\_id, pool, crm, health, webhook, connected or test |
| Voice and chat agents | `/agents`; `type` chat for chat agents; `GET /agents/{id}/context`; `POST /agents/{id}/actions` |
| Custom voices, including cloning | `/custom-voices`; `type` clone on create |
| Phone numbers | `/phone-numbers` (search, read, import, ordering documents, settings) and `POST /phone-numbers/{id}/actions` |
| Buying | `POST /purchases` with `step` quote or buy, and `GET /purchases` |
| Settings, team, roles and billing | `/workspace-settings` |
| Campaigns, folders, templates, settings, import | `/campaigns`; `type` folder or template; `include=config.*`; `config` on update; `type` import on create; `POST /campaigns/{campaign_id}/actions` |
| Tools and website widgets | `/agent-resources` with `type` tool or widget |
| Deliverability tests | `/connections` with `type` test and `test` blacklist or placement |
| Lead details | `GET /leads?id=&include=`, `PATCH /leads/{id}` (with `context`), `POST /leads/bulk` |
| Inbox buttons | `POST /conversations/{lead_id}/actions` |
| Agency clients, packages, pricing | `/partner/clients`, `/partner/packages`, `/partner/pricing` |
| Call recordings | `GET /calls/{call_id}/recording` |

## Read several parts in one call

Reads take `include`, a comma list, so one request replaces many.

```bash theme={"dark"}
curl "https://api.sendora.ai/api/v1/public/workspace-settings?include=org,ai_reply,holidays,team" -H "X-API-Key: sk_live_..."
curl "https://api.sendora.ai/api/v1/public/workspace-settings?include=billing.wallet,billing.subscription,billing.cap" -H "X-API-Key: sk_live_..."
curl "https://api.sendora.ai/api/v1/public/agents/AGENT_ID/context?type=chat&include=channels,settings,approvals" -H "X-API-Key: sk_live_..."
```

## Change several settings in one call

A `PATCH` takes only what should change and runs its steps in a fixed order. If one step is refused, the earlier steps stay applied.

```bash theme={"dark"}
curl -X PATCH "https://api.sendora.ai/api/v1/public/agents/AGENT_ID" \
  -H "X-API-Key: sk_live_..." -H "Content-Type: application/json" \
  -d '{"type": "chat", "chat": {"channels": {"sms": {"account_id": "ACCOUNT_ID", "mode": "draft"}}, "followup": {"nudge_after_minutes": 60, "nudge_max": 2}}}'
```

## Work that waits on a person

`GET /work-items?view=attention` lists everything waiting on a person, most urgent first. Act on each kind:

* **Approvals**: `POST /work-items/{id}/actions` with `{"type": "approval", "decision": "approved"}` or `"rejected"`. A second decision answers `409`.
* **Escalations**: `PATCH /work-items/{id}` with `{"type": "escalation", "status": ...}`. Resolving needs `resolution_type`: `retry` runs the failed step again, `skip` moves on, `manual` only marks it fixed.
* **Tasks**: `PATCH /work-items/{id}` with `{"type": "task", "status": ...}`.
* **Meetings**: `POST /work-items` with `{"type": "meeting", ...}` records one; `PATCH` and `DELETE` change or cancel a manual one.
* **Conversations**: `POST /conversations/{lead_id}/actions` with `mark_read`, `archive`, `snooze` (`snoozed_until`), `pause_outreach`, `set_pipeline_stage`, `mark_meeting_booked`, `delete` (undo with `restore`) and more.

## Sending accounts, domains and pools

`GET /connections?type=account` lists the accounts you send from; `type=domain` lists email domains (`include=dns` adds the live records). A sender pool groups accounts or phone numbers under one rotation rule (`least_used`, `round_robin`, `weighted` or `sticky_by_lead`); add members in the same `PATCH` that changes anything else.

```bash theme={"dark"}
curl -X PATCH "https://api.sendora.ai/api/v1/public/connections/POOL_ID" \
  -H "X-API-Key: sk_live_..." -H "Content-Type: application/json" \
  -d '{"type": "pool", "add_members": [{"account_id": "ACCOUNT_ID", "kind": "account", "weight": 2}], "member_settings": {"OTHER_ACCOUNT_ID": {"paused": true}}}'
```

## CRMs and integration health

`GET /connections?type=crm` lists the CRMs you connected. A connection's `id` is its provider name, for example `hubspot`. Signing in to a CRM needs the owner to approve access in the app, so connecting stays there; everything after that is here: sync settings, field mapping, `test`, `sync` and `import` (use `dry_run` first to count without writing). `GET /connections?type=health` shows which connected accounts work and which need a person; `POST /connections/{id}/actions` with `{"type": "health", "action": "check"}` queues a fresh check.

## The team, roles and settings

`GET /workspace-settings?include=team` lists members and invitations. `POST /workspace-settings/actions` invites, resends, revokes, suspends, reactivates and removes members and makes an owner (`invite`, `resend_invite`, `revoke`, `suspend`, `reactivate`, `make_owner`, `remove_member`), and adds or removes holidays. Only owners and admins can manage the team, and a key acts with the live role of the person who created it, so a key created by a manager cannot.

`include=access_catalog` lists the roles and permissions; `include=member_access&member_id=` shows one member's. `PATCH /workspace-settings` with `team_access` replaces a member's role, extra grants or denials, and the campaigns or lead lists they are limited to. You cannot change your own access or the owner's, cannot give a permission you do not hold, and one other admin must remain.

## Billing

Billing is read only, as `include=billing.*` on `GET /workspace-settings`: balance and cycle, plan and status, this month's usage, the spend cap and credit activity. Buying credits, changing plan and payment methods stay in the app, where the owner confirms them.

## Phone numbers, start to finish

1. **Search**: `GET /phone-numbers?view=available&country_code=US&search_by=area_code&search_value=415` returns numbers with the price due now and monthly. Some countries need an address or document first: `GET /phone-numbers?view=requirements&phone_number=...`, then `POST /phone-numbers` with `step` `regulatory_address` or `regulatory_document`.
2. **Quote**: `POST /purchases` with `{"step": "quote", "kind": "phone_number", "selection": {"phone_number": "+14155550100"}}`. Nothing is charged.
3. **Buy**: `POST /purchases` with `{"step": "buy", "kind": "phone_number", "quote_id": ..., "pay_with": "wallet"}` (or `card`, which returns a checkout link a person opens) and an `Idempotency-Key`. A changed price answers `409`; ask for a new quote. Follow the result with `GET /purchases?operation_id=`.
4. **Set up**: `PATCH /phone-numbers/{id}` sets the inbound agent, outbound calling, the agent a number belongs to, its caller ID name, a verified caller ID and the sender ID.
5. **Look after it**: `GET /phone-numbers?id=...&include=history,usage` shows recent texts and calls and what uses the number. `POST /phone-numbers/{id}/actions` can `retry` setup, send a `test_message`, `send_documents` the carrier asked for, or `release` it (a number that campaigns or agents use answers `409` with the list until `confirm_unassign` is true).

Domains, mailboxes and WhatsApp accounts are bought the same way with their own `kind`. Numbers from your own carrier account are imported with `POST /phone-numbers` (`step` search, confirm, outbound\_profile, or twilio\_search and twilio\_confirm for your own Twilio account) and cost nothing.

## Cloning a voice

`POST /custom-voices` with `"type": "clone"` takes a speech sample as `audio_url` (a public https link, up to 50 MB) or `audio_base64` (up to 10 MB), plus `name`, `gender`, `nationality` and `consent_confirmed: true`. The provider charges for each clone, so send an `Idempotency-Key` and do not retry blindly. Without `type`, the same call adds a voice you already have at your speech provider.

## Agency clients over their lifetime

`GET /partner/clients?id=...&include=details,limits,audit,users` shows one client with 30 days of usage and revenue, its monthly caps and access, what it did and what you changed, and its own people. `PATCH /partner/clients/{id}` changes branding, features, `profile` (name, owner, notes, renewal), `usage_caps`, `access` and `users` (invite, update, remove by email). `POST .../actions` activates, suspends, sets trial or closes a client (closing needs the exact name and can be undone in the app for 30 days). `GET /partner/packages` lists the plans you sell, `POST /partner/packages` creates one or, with `package_id`, publishes a new version, and `PUT /partner/pricing` saves and publishes your markup (publishing pricing is needed before packages).

## Recordings

`GET /calls/{call_id}/recording` returns a call's audio.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.