> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.formantai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.formantai.com/_mcp/server.

# API Overview

> Understand FormantAI Voice REST API structure, auth, resources, and usage patterns.

The FormantAI Voice API lets your backend initiate calls, launch batch campaigns, retrieve conversations, download recordings, and submit transcription jobs.

## Base URL

```text
https://api.voice.formantai.com
```

Regional environments:

| Region | Base URL                             |
| ------ | ------------------------------------ |
| Global | `https://api.voice.formantai.com`    |
| India  | `https://api.in.voice.formantai.com` |

## Authentication

Use an API key as a bearer token.

```http
Authorization: Bearer YOUR_API_KEY
```

## Resources

| Resource      | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| Calls         | Start one outbound call immediately or schedule one for later.          |
| Batch Calls   | Upload CSV campaigns and inspect campaign metrics.                      |
| Conversations | Retrieve call history, transcripts, results, trace IDs, and recordings. |
| Transcription | Submit audio files for asynchronous transcription.                      |
| Webhooks      | Receive real-time terminal call events without polling.                 |

## Request formats

* JSON endpoints require `Content-Type: application/json`.
* File upload endpoints use `multipart/form-data`.
* List endpoints use `limit` and `offset` pagination.

## Recommended integration order

1. Create an API key in the dashboard.
2. Select or create an agent.
3. Make one test call with `POST /v1/call`.
4. Configure a webhook target on the agent.
5. Fetch the completed conversation to confirm transcript, results, and recording.
6. Add batch calls if your workflow needs campaigns.

## Important IDs

| ID                | Where it comes from                    | Where it is used                                           |
| ----------------- | -------------------------------------- | ---------------------------------------------------------- |
| `agent_id`        | Dashboard agent page                   | Calls, batch calls, conversation filters, webhook payloads |
| `conversation_id` | Conversation record or webhook payload | Fetch details and recordings                               |
| `trace_id`        | `POST /v1/call` response               | Debugging and support                                      |
| `batch_id`        | `POST /v1/batch-call` response         | Fetch batch detail and metrics                             |
| `event_id`        | Webhook delivery                       | Dedupe webhook processing                                  |

## Next steps

Start with the most important endpoint.

Receive real-time call outcomes.