Quickstart

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.

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.

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.

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.

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.

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

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.

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

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.

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

The conversation record can include:

Step 5: Download the recording

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

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