# API Reference

> Every Edesy Cloud Contact Center REST endpoint under /v1/ccaas - agents, queues, skills, contacts, dispositions, metrics, reports, monitoring, insights, recordings and webhook logs.

Source: https://edesy.in/docs/contact-center/api

The Edesy Cloud Contact Center API is a REST API at `https://voice-api.edesy.in/v1/ccaas`. It manages agents, queues, skills, contacts and dispositions, returns live metrics and daily reports, starts supervisor monitoring, and serves AI call insights and recordings. Authenticate with an API key in the `Authorization: Bearer` header. API access is part of the Professional and Enterprise plans.

## Authentication

| Item | Detail |
|---|---|
| Base URL | `https://voice-api.edesy.in/v1` |
| Header | `Authorization: Bearer sk_your_api_key` (or `X-API-Key: sk_...`) |
| Also accepted | Twilio-style Basic auth with `AccountSid:AuthToken` |
| Keys | Create and revoke in *API Keys* in [voice-app.edesy.in](https://voice-app.edesy.in) |
| WebSockets | Use a signed-in user's access token, not an API key. See [WebSocket events](https://edesy.in/docs/contact-center/api/websocket-events) |

## Response format

Single objects come back as `{"data": {...}}`. Lists come back as `{"data": [...], "meta": {"page": 1, "per_page": 20, "total": 42, "total_pages": 3}}` and accept `page` and `per_page`. Errors look like:

```json
{"error": {"code": "QUEUE_NOT_FOUND", "message": "queue not found"}}
```

## Endpoints

All paths are relative to `https://voice-api.edesy.in/v1`.

### Agents

| Method | Path | Description |
|---|---|---|
| `POST` | `/ccaas/agents` | Create an agent (`user_id`, `agent_number`, `display_name`, `max_concurrent_calls`, `skill_ids`, ...) |
| `GET` | `/ccaas/agents` | List agents (`status`, `search`, `is_active`, `page`, `per_page`) |
| `GET` | `/ccaas/agents/{id}` | Get an agent |
| `PATCH` | `/ccaas/agents/{id}` | Update an agent |
| `DELETE` | `/ccaas/agents/{id}` | Delete an agent and free the seat |
| `POST` | `/ccaas/agents/{id}/login` | Log an agent in |
| `POST` | `/ccaas/agents/{id}/logout` | Log an agent out |
| `PATCH` | `/ccaas/agents/{id}/status` | Set `status` and `status_reason` |
| `GET` | `/ccaas/agents/{id}/calls` | An agent's calls |
| `GET` | `/ccaas/agents/me` | The agent record of the signed-in user |
| `GET` | `/ccaas/agents/me/calls` | The signed-in agent's call history |
| `POST` | `/ccaas/agents/me/disposition` | Submit a wrap-up code (`direction`, `disposition_id`, `notes`) |

### Queues

| Method | Path | Description |
|---|---|---|
| `POST` | `/ccaas/queues` | Create a queue |
| `GET` | `/ccaas/queues` | List queues |
| `GET` | `/ccaas/queues/{id}` | Get a queue |
| `PATCH` | `/ccaas/queues/{id}` | Update a queue (strategy, skill, number, hold music, ...) |
| `DELETE` | `/ccaas/queues/{id}` | Deactivate a queue |
| `GET` | `/ccaas/queues/{id}/members` | List members |
| `POST` | `/ccaas/queues/{id}/members` | Add a member (`agent_id`, `priority`, `penalty`) |
| `DELETE` | `/ccaas/queues/{id}/members/{agent_id}` | Remove a member |
| `GET` | `/ccaas/queues/{id}/status` | Live waiting calls, longest wait, agents available, service level |

### Skills, contacts and dispositions

| Method | Path | Description |
|---|---|---|
| `POST` `GET` | `/ccaas/skills` | Create or list skills |
| `GET` `PATCH` `DELETE` | `/ccaas/skills/{id}` | Get, update or delete a skill |
| `GET` | `/ccaas/contacts?q=` | List or search contacts (name, number, company) |
| `GET` | `/ccaas/contacts/lookup?number=` | Screen-pop: match a caller number to a contact (last 10 digits) |
| `POST` | `/ccaas/contacts` | Create a contact (`name`, `number`, `company`, `email`, `notes`) |
| `PATCH` `DELETE` | `/ccaas/contacts/{id}` | Update or delete a contact |
| `GET` `POST` | `/ccaas/dispositions` | List or create wrap-up codes |
| `PATCH` `DELETE` | `/ccaas/dispositions/{id}` | Update or delete a wrap-up code |

### Supervision, reports and AI

| Method | Path | Description |
|---|---|---|
| `GET` | `/ccaas/metrics/realtime` | Live dashboard numbers |
| `GET` | `/ccaas/reports/agents?from=&to=` | Daily agent rows (max 92 days) |
| `GET` | `/ccaas/reports/agents/{id}?from=&to=` | One agent's trend and disposition breakdown |
| `GET` | `/ccaas/reports/queues?from=&to=` | Daily queue rows |
| `GET` | `/ccaas/calls/active` | Calls connected to agents now |
| `POST` | `/ccaas/calls/{id}/monitor` | Listen, whisper or barge (`mode`, `to`) |
| `GET` | `/ccaas/calls/{callSid}/insights` | AI transcript, summary, key points, sentiment, suggested disposition |

### Recordings and webhook logs

| Method | Path | Description |
|---|---|---|
| `GET` | `/ccaas/recordings` | List recordings |
| `GET` | `/ccaas/recordings/{recording_sid}` | Recording details |
| `GET` | `/ccaas/recordings/{recording_sid}/media` | Stream the audio |
| `GET` | `/ccaas/recordings/{recording_sid}/download` | Download the audio |
| `DELETE` | `/ccaas/recordings/{recording_sid}` | Delete a recording |
| `GET` | `/ccaas/webhook-logs` | Webhook delivery log |
| `GET` | `/ccaas/webhook-logs/{id}` | One delivery with request and response |
| `POST` | `/ccaas/webhook-logs/{id}/retry` | Retry a delivery |

## Error codes

| HTTP | Code | When |
|---|---|---|
| 404 | `AGENT_NOT_FOUND`, `QUEUE_NOT_FOUND`, `SKILL_NOT_FOUND`, `DISPOSITION_NOT_FOUND` | The ID does not exist in your workspace |
| 409 | `AGENT_EXISTS`, `QUEUE_EXISTS` | Duplicate agent number or queue name |
| 409 | `QUEUE_FULL`, `NO_AVAILABLE_AGENTS` | Capacity conditions |
| 402 | `NO_AVAILABLE_SEATS` | All seats are used |
| 409 | `NOT_ACTIVE` | Monitoring a call that is no longer connected |

## How to integrate

1. **Create an API key** in voice-app.edesy.in.
2. **Create skills, agents and queues** with the endpoints above, or in the portal.
3. **Sync contacts** from your CRM to `/ccaas/contacts` so agents get screen-pop.
4. **Read live numbers** from `/ccaas/metrics/realtime` and history from `/ccaas/reports/*`.
5. **Receive outcomes** through [webhooks](https://edesy.in/docs/contact-center/api/webhooks).

## FAQ

### Is there an SDK for the contact-center API?
No. Use any HTTP client.

### Can I create agents without the portal?
Yes, with `POST /ccaas/agents`. The agent still needs an Edesy user (`user_id`) to sign in to the desktop.

### Can I place an outbound call for an agent through the API?
Agents place calls from the agent desktop. For automated outbound calling to agents, use an [agent dialer campaign](https://edesy.in/docs/contact-center/dialer/agent-dialer-campaigns).

### How do I find a phone number ID for a queue?
`GET /v1/phone-numbers` lists your numbers with their IDs.

### Is there a rate limit?
Use reasonable polling intervals, such as 10-15 seconds for live metrics, as the portal does. Prefer [WebSocket events](https://edesy.in/docs/contact-center/api/websocket-events) for live status.

### Which plan includes API access?
Professional and Enterprise.