# Call lists

## Call a list of people

Upload the people (an Excel `.xlsx`, a CSV, a shared Google Sheet, or JSON
rows), pick an agent and a phone line, set calling hours and start. We call
each person through the same door as `POST /v2/voice/sessions/outbound`, a
few at a time, so every call is admitted, held and billed exactly like a call
you placed yourself (₹0.50 or $0.005 per connected minute). The list itself is
free.

```bash
# 1. Make the list (nobody is called yet)
curl -X POST https://api.developers.dvaarik.com/v2/call-lists \
  -H "X-Api-Key: $DVAARIK_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Renewals","agent_id":"AGENT_ID","from":"+918000000000",
       "settings":{"window_start":"10:00","window_end":"19:00","calls_at_once":3,"max_attempts":2}}'

# 2. Add people: a file as the raw body, a Google Sheet link, or JSON rows
curl -X POST "https://api.developers.dvaarik.com/v2/call-lists/LIST_ID/rows/file?filename=people.xlsx" \
  -H "X-Api-Key: $DVAARIK_KEY" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  --data-binary @people.xlsx

# 3. Start
curl -X POST https://api.developers.dvaarik.com/v2/call-lists/LIST_ID/start -H "X-Api-Key: $DVAARIK_KEY"
```

## How rows become calls

- **The phone column** is the one named phone, mobile, number, to or contact
  (or the one you name with `phone_column`). Numbers without a country
  code get the list's `default_country_code` (91 unless you change it).
- **Columns named like your agent's variables** (case, spaces and underscores
  ignored) fill them: a `First Name` column fills `{{first_name}}`. A variable
  the agent cannot do without needs a column, and each row needs a value.
- **Every other column** rides along on the call as `metadata.row`, so it comes
  back in webhooks and in the results file. Calls carry
  `metadata.call_list_id` and `metadata.call_list_row_id` too.
- A number that appears twice is called once. Rows that cannot be called (not a
  phone number, a paid-rate or satellite range, a missing value) are skipped and named in
  `issues`. `POST .../preview/file` and `.../preview/sheet` show all of this
  without saving anything.
- Limits: 10,000 people per list, 5 MB per file, 64 columns, 20 open lists per
  project. A Google Sheet must be shared as "Anyone with the link can view".

## Settings

| Setting | Default | Meaning |
| --- | --- | --- |
| `calls_at_once` | 5 (never above the project's limit) | How many people are on the phone at the same time |
| `window_start` / `window_end` | 09:00 / 21:00 | Calling hours, 24-hour clock; an end before the start runs overnight |
| `days` | every day | `mon` … `sun` |
| `timezone` | Asia/Kolkata | Any IANA place name |
| `max_attempts` | 1 (up to 3) | Tries per person; only no answer, busy and failed are tried again |
| `retry_after_minutes` | 60 (15 to 1,440) | The wait before the next try |
| `default_country_code` | 91 | For numbers written without one |

## States

`draft` → `start` → `running` ⇄ `pause` / `resume` → `finished` when
nobody is waiting or on a call. `cancel` skips everyone not yet called; calls
already ringing finish. A list **pauses by itself** with a plain
`pause_reason` when your balance runs out, its agent is deleted or switched
off, its phone line stops calling out, or your AI account is refused; fix it and
`resume`. Nobody is ever called twice for one try: each try has its own
idempotency key.

## Results

`GET /v2/call-lists/{list_id}/rows` pages through the people with their
status, tries and outcome (`answered`, `voicemail`, `no_answer`, `busy`,
`failed`, `do_not_call`, …). `GET .../results.csv` is everyone at once with
the call id, connected seconds and cost in your wallet's currency; it opens in
Excel.

## Do not call

`POST /v2/do-not-call` with `{"numbers": [...]}` (or upload a file to
`/v2/do-not-call/file`) adds numbers your project must never call. Call lists
skip them, and a single outbound call to one is refused with a 422 before any
money is held. `DELETE /v2/do-not-call/{phone_number}` removes one.

---

Source: https://developers.dvaarik.com/docs/call-lists · every page as one file: https://developers.dvaarik.com/docs.md