> 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.

# Quickstart

> Make your first FormantAI Voice call and retrieve the result.

This guide takes you from a configured agent to a completed call result. You will create an API key, start one outbound call, wait for the final call state, and retrieve the conversation record.

10 minutes once your workspace and agent are ready.

Your backend calls the FormantAI Voice API with a bearer API key.

A conversation with status, transcript, recording, results, and trace ID.

***

## Before you begin

You need:

* A FormantAI Voice workspace.
* A configured agent with a phone number.
* The agent ID from the agent detail page.
* A backend environment where you can store an API key securely.
* A test phone number that can receive the call.

If your agent is not configured yet, start with [Create your first agent](/getting-started/create-agent).

***

## Step 1: Create an API key

Open your FormantAI dashboard and create an API key from **Developer -> API Keys**. Copy it immediately. API keys are shown once and should only be used from your backend.

```bash
export FORMANT_API_KEY="YOUR_API_KEY"
export FORMANT_API_BASE="https://api.voice.formantai.com"
export FORMANT_AGENT_ID="123"
```

Use `https://api.in.voice.formantai.com` only if your workspace is provisioned in the India region.

***

## Step 2: Start one outbound call

Every outbound call needs an `agent_id` and a `customer_phone` parameter. Add any other parameters your prompt, tools, webhooks, or result extraction need.

```bash
curl -X POST "$FORMANT_API_BASE/v1/call" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 123,
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {
      "source": "quickstart",
      "crm_record_id": "lead_123"
    },
    "parameters": [
      { "name": "customer_phone", "value": "+14155550123" },
      { "name": "customer_name", "value": "Alex" },
      { "name": "account_tier", "value": "enterprise" }
    ]
  }'
```

The response confirms that FormantAI accepted the call request. Store the `trace_id`; it is your support and debugging handle.

```json
{
  "data": {
    "agent_id": 123,
    "conversation_id": null,
    "scheduled_for": null,
    "status": "initiated",
    "trace_id": "f9e8d7c6-1234-4d5e-8f90-123456789abc"
  }
}
```

`conversation_id` can be `null` immediately after initiation because the telephony provider and live conversation record may be created asynchronously.

***

## Step 3: Wait for the terminal event

The cleanest production path is to configure webhooks and wait for a terminal event such as `call.completed`, `call.no_answer`, or `call.failed`.

Send terminal call events to your CRM, backend, data warehouse, or workflow engine.

If you are not using webhooks yet, wait for the call to finish and list conversations for the agent.

```bash
curl "$FORMANT_API_BASE/v1/conversations?agent_id=$FORMANT_AGENT_ID&limit=20" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
```

***

## Step 4: Fetch the conversation

Use the returned `conversation_id` to fetch the full call record.

```bash
curl "$FORMANT_API_BASE/v1/conversations/e36853de-9cbb-441e-ad75-d3c8ac82abfb_1" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
```

The conversation record can include:

| Field           | Description                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `status`        | Terminal or in-progress call state, such as completed, no answer, busy, failed, or provider-specific failure. |
| `trace_id`      | Correlation ID for debugging API initiation, live call handling, webhook delivery, and support requests.      |
| `transcript`    | Ordered caller and agent turns when transcript capture is available.                                          |
| `results`       | Structured fields extracted from the call according to your agent configuration.                              |
| `recording_url` | Recording URL or recording retrieval handle when a recording is available.                                    |

***

## Step 5: Download the recording

When the call has a recording, download it from the Conversations API.

```bash
curl "$FORMANT_API_BASE/v1/conversations/e36853de-9cbb-441e-ad75-d3c8ac82abfb_1/recording" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  --output recording.mp3
```

***

## Production next steps

Review idempotency, rate limits, webhooks, monitoring, consent, and retry handling.

Retrieve call records, transcripts, structured results, statuses, trace IDs, and recordings.