# API Overview

> Call Forwarding REST API - base URL, authentication with a Bearer API key, response and error format, and the list of endpoints for rules, hold audio, call logs, recordings, stats and analytics.

Source: https://edesy.in/docs/call-forwarding/api

The Call Forwarding API lets you do from code everything the forwarding.edesy.in portal does: create and change forwarding rules, upload hold audio, turn forwarding off, list forwarded calls, fetch recordings and read usage stats. It is a JSON REST API at `https://voice-api.edesy.in/v1`, authenticated with a Bearer API key from your workspace.

## Base URL and authentication

```
https://voice-api.edesy.in/v1
```

Create an API key under **API Keys** in the portal. The key is shown once, so copy it somewhere safe. Send it on every request:

```
Authorization: Bearer sk_your_api_key
```

A key belongs to the workspace it was created in and can only set up forwarding on that workspace's numbers.

## Response format

Successful responses wrap the result in `data`, with `meta`:

```json
{ "data": { "id": "3f2b8c1e-7d4a-4e59-9b21-6a0c5d8e1f47", "status": "active" }, "meta": { "timestamp": "2026-10-16T09:30:00Z" } }
```

Errors return an HTTP status and an `error` object:

```json
{ "error": { "code": "not_found", "message": "Forwarding rule not found" } }
```

## Endpoints

| Method | Path | What it does |
|---|---|---|
| `POST` | `/forwarding/rules` | [Turn on forwarding for a number](https://edesy.in/docs/call-forwarding/api/rules#create-a-rule) |
| `GET` | `/forwarding/rules` | [List your rules](https://edesy.in/docs/call-forwarding/api/rules#list-rules) |
| `GET` | `/forwarding/rules/:id` | [Get one rule](https://edesy.in/docs/call-forwarding/api/rules#get-a-rule) |
| `PATCH` | `/forwarding/rules/:id` | [Change a rule](https://edesy.in/docs/call-forwarding/api/rules#update-a-rule) |
| `POST` | `/forwarding/rules/:id/disable` | [Turn off forwarding](https://edesy.in/docs/call-forwarding/api/rules#turn-off-forwarding) |
| `DELETE` | `/forwarding/rules/:id` | [Delete a rule](https://edesy.in/docs/call-forwarding/api/rules#delete-a-rule) |
| `POST` | `/forwarding/rules/:id/hold-audio` | [Upload hold audio](https://edesy.in/docs/call-forwarding/api/rules#hold-audio) |
| `DELETE` | `/forwarding/rules/:id/hold-audio` | [Remove hold audio](https://edesy.in/docs/call-forwarding/api/rules#hold-audio) |
| `GET` | `/forwarding/call-logs` | [List forwarded calls](https://edesy.in/docs/call-forwarding/api/call-logs) |
| `GET` | `/forwarding/calls/:call_sid/recording` | [Get a recording link](https://edesy.in/docs/call-forwarding/api/call-logs#get-a-recording-link) |
| `GET` | `/forwarding/stats` | [Usage totals](https://edesy.in/docs/call-forwarding/api/stats#usage-totals) |
| `GET` | `/forwarding/analytics` | [Daily and per-number breakdown](https://edesy.in/docs/call-forwarding/api/stats#analytics) |

To find the numbers in your workspace, use `GET /v1/phone-numbers`.

## Common errors

| Status | Code | Meaning |
|---|---|---|
| 400 | `validation_error` | A field is missing or out of range. The message names the field |
| 400 | `targets_required` | No number to forward to |
| 401 | `UNAUTHORIZED` | API key missing, mistyped or revoked |
| 404 | `number_not_found` | The number is not in the workspace your key belongs to |
| 404 | `not_found` | No rule with this id in your workspace |
| 409 | `rule_exists` | Another account still has forwarding on this number. Contact support |
| 413 | `file_too_large` | Hold audio over 8 MB |
| 502 | `inbound_activation_failed` | The rule was saved but not switched on yet. Send the same request again |
| 502 | `inbound_repoint_failed` | Forwarding is off, but handing the number back did not finish. Retry |