Quickstart

This quickstart walks you through sending your first AI phone call with the Bland API. By the end, you’ll have placed a live call from a script.

Working through an AI agent (Claude Code, Cursor, Codex, or your own)? You usually don’t need to hand-write these HTTP calls. The hosted Bland MCP server exposes the same operations as tools, with nothing to install. The REST calls below are what those tools run underneath.

Prerequisites

A Bland account
Your API key from the dashboard
A phone number to call (include the country code, e.g. +15551234567)

Step 1: Get your API key

Sign in to the Bland dashboard.
Open Settings and copy your API key.
Store it as an environment variable so you don’t commit it to source:

export BLAND_API_KEY="your-api-key-here"

How to send the key

Every Bland request authenticates with that key in the Authorization header.

Header	Supported
`Authorization: Bearer YOUR_API_KEY`	Yes. This is the canonical form, and what the MCP server, SIP, and Speech endpoints use. Prefer it.
`Authorization: YOUR_API_KEY`	Yes. The bare key with no prefix is also accepted, so older examples and integrations keep working.
`x-api-key: YOUR_API_KEY`	No. Bland does not read this header, and a request that only sets it is unauthenticated.

Building an autonomous agent with no dashboard session to sign into? It can get its own key without a human ever pasting one in. See the Agent onboarding API.

Step 2: Send a call

Use the POST /v1/calls endpoint to dispatch a call. The task field describes what the AI agent should do on the call.

curl -X POST https://api.bland.ai/v1/calls \
  -H "Authorization: Bearer $BLAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "task": "You are calling to confirm a dentist appointment for tomorrow at 2pm. Be polite and friendly.",
    "voice": "Karen",
    "record": true
  }'

const response = await fetch("https://api.bland.ai/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLAND_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+15551234567",
    task: "You are calling to confirm a dentist appointment for tomorrow at 2pm. Be polite and friendly.",
    voice: "Karen",
    record: true,
  }),
});

const data = await response.json();
console.log(data);

import os
import requests

response = requests.post(
    "https://api.bland.ai/v1/calls",
    headers={"Authorization": f"Bearer {os.environ['BLAND_API_KEY']}"},
    json={
        "phone_number": "+15551234567",
        "task": "You are calling to confirm a dentist appointment for tomorrow at 2pm. Be polite and friendly.",
        "voice": "Karen",
        "record": True,
    },
)

print(response.json())

A successful response returns a call_id you can use to track the call:

{
  "status": "success",
  "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1"
}

Step 3: Check the call status

Use the call_id to fetch call details, including the transcript and recording URL once the call completes.

curl https://api.bland.ai/v1/calls/$CALL_ID \
  -H "Authorization: Bearer $BLAND_API_KEY"

You can also watch calls in real time on the Call Logs page.

Common parameters

Parameter	Description
`phone_number`	The number to call, in E.164 format (e.g. `+15551234567`).
`task`	Plain-language instructions for the agent.
`voice`	Voice persona for the agent. Browse options in the dashboard.
`first_sentence`	The first line the agent speaks.
`wait_for_greeting`	If `true`, the agent waits for the recipient to speak first.
`max_duration`	Maximum call length in minutes.
`record`	Set to `true` to record the call.
`webhook`	URL to receive a post-call payload with transcript and metadata.

See the Send Call API reference for the full list.

Next steps

Send 1,000 calls at once

Batch dispatch calls from a CSV or list.

Build a conversational pathway

Design branching conversations with structured logic.

Set up post-call webhooks

Receive transcripts and analysis after each call.

Create an agent persona

Define reusable agent personalities across calls.

Connect your AI coding agent

Give Claude Code, Cursor, or Codex your Bland account via MCP.

Agent quickstart

Place a call, learn how it ended, and read the transcript, from an autonomous agent.

Core Bland Features

AI Agents & MCP

Basic Tutorials

Advanced Features

Platform Information

SDKs & Tools

Bland Enterprise

Prerequisites

Step 1: Get your API key

How to send the key

Step 2: Send a call

Step 3: Check the call status

Common parameters

Next steps

Send 1,000 calls at once

Build a conversational pathway

Set up post-call webhooks

Create an agent persona

Connect your AI coding agent

Agent quickstart

​Prerequisites

​Step 1: Get your API key

​How to send the key

​Step 2: Send a call

​Step 3: Check the call status

​Common parameters

​Next steps

Send 1,000 calls at once

Build a conversational pathway

Set up post-call webhooks

Create an agent persona

Connect your AI coding agent

Agent quickstart

Prerequisites

Step 1: Get your API key

How to send the key

Step 2: Send a call

Step 3: Check the call status

Common parameters

Next steps