# API Overview

> Edesy Collect REST API - base URL, authentication with an API key, and every endpoint for plans, caller-ID pools, reminder campaigns, debtors and payment signals.

Source: https://edesy.in/docs/collect/api

The Edesy Collect API lets you run payment-reminder campaigns from your own system. Every action in the Collect portal is an endpoint under `https://voice-api.edesy.in/v1/collect`, authenticated with an Edesy API key in the `Authorization: Bearer` header. Responses are JSON, with results in a `data` field.

## Base URL and authentication

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

Create an API key in your Edesy workspace and send it on every request:

```bash
curl https://voice-api.edesy.in/v1/collect/pools \
  -H "Authorization: Bearer sk_your_api_key"
```

Twilio-style Basic auth with your Account SID and Auth Token also works. Keep keys on your server; never put them in a browser or app.

## Endpoints

### Plans

| Method | Path | Description |
|---|---|---|
| GET | `/plans` | Plan catalog |
| GET | `/plan` | Your current plan, or `null` |
| POST | `/plan` | Start a Razorpay auto-pay subscription (KYC required) |
| POST | `/plan/cancel` | Cancel auto-pay |

See [Plans](https://edesy.in/docs/collect/api/plans).

### Number pools

| Method | Path | Description |
|---|---|---|
| POST | `/pools` | Create a pool |
| GET | `/pools` | List pools |
| DELETE | `/pools/:id` | Delete a pool |
| POST | `/pools/:id/numbers` | Add a number to a pool |
| GET | `/pools/:id/numbers` | List a pool's numbers with health |
| DELETE | `/pools/:id/numbers/:memberId` | Remove a number from a pool |
| PATCH | `/pools/:id/numbers/:memberId/health` | Set `active`, `flagged` or `retired` |

See [Number Pools](https://edesy.in/docs/collect/api/pools).

### Reminder campaigns

| Method | Path | Description |
|---|---|---|
| POST | `/campaigns` | Create a reminder campaign |
| POST | `/campaigns/:id/message` | Save and render the message |
| POST | `/campaigns/:id/contacts` | Upload debtors (KYC required) |
| POST | `/campaigns/:id/start` | Start (KYC required) |

See [Campaigns](https://edesy.in/docs/collect/api/campaigns).

### Contacts and payment signals

| Method | Path | Description |
|---|---|---|
| POST | `/contacts/:id/paid` | Mark a debtor paid |
| POST | `/contacts/:id/promised` | Mark a debtor promised |
| POST | `/contacts/:id/stop` | Stop calling a debtor |
| POST | `/webhooks/payment` | Set a debtor's status from your payment system |

See [Contacts and Payments](https://edesy.in/docs/collect/api/contacts-and-payments).

### Shared campaign endpoints

Reading and controlling a reminder campaign uses the shared campaign API at `https://voice-api.edesy.in/v1/campaigns` with the same key:

| Method | Path | Description |
|---|---|---|
| GET | `/v1/campaigns` | List campaigns; reminder campaigns have `is_reminder: true` |
| GET | `/v1/campaigns/:id` | One campaign with counts |
| GET | `/v1/campaigns/:id/contacts` | Debtors, with `id`, `payment_status`, `attempts_total`, `next_attempt_at` |
| POST | `/v1/campaigns/:id/pause` | Pause |
| POST | `/v1/campaigns/:id/resume` | Resume |
| POST | `/v1/campaigns/:id/stop` | Stop |

## Errors

| Status | When |
|---|---|
| `400` | Invalid body or field, for example an unknown rotation, a bad `due_date` or a full pool |
| `401` | Missing or invalid API key |
| `403` | `KYC_NOT_APPROVED` on upload, start or subscribe |
| `404` | The pool, campaign or contact is not in your workspace |
| `503` | Subscriptions are not available right now |

```json
{
  "error": {
    "code": "KYC_NOT_APPROVED",
    "message": "Please complete KYC verification before running reminder campaigns."
  }
}
```