> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Send your first AI phone call with Bland in under 5 minutes

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.

<Note>
  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](/integrations/mcp/overview) exposes the same operations as tools, with nothing to install. The REST calls below are what those tools run underneath.
</Note>

## Prerequisites

* A [Bland account](https://app.bland.ai)
* Your API key from the [dashboard](https://app.bland.ai/dashboard/settings)
* A phone number to call (include the country code, e.g. `+15551234567`)

## Step 1: Get your API key

1. Sign in to the [Bland dashboard](https://app.bland.ai).
2. Open **Settings** and copy your API key.
3. Store it as an environment variable so you don't commit it to source:

```bash theme={null}
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.            |

<Note>
  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](/platform/connect-your-agent).
</Note>

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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

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

```json theme={null}
{
  "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.

```bash theme={null}
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](https://app.bland.ai/dashboard/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](/api-v1/post/calls) for the full list.

## Next steps

<CardGroup cols={2}>
  <Card title="Send 1,000 calls at once" icon="megaphone" href="/tutorials/send-1000-calls-at-once">
    Batch dispatch calls from a CSV or list.
  </Card>

  <Card title="Build a conversational pathway" icon="diagram-project" href="/tutorials/pathways">
    Design branching conversations with structured logic.
  </Card>

  <Card title="Set up post-call webhooks" icon="webhook" href="/tutorials/post-call-webhooks">
    Receive transcripts and analysis after each call.
  </Card>

  <Card title="Create an agent persona" icon="user-robot" href="/tutorials/personas">
    Define reusable agent personalities across calls.
  </Card>

  <Card title="Connect your AI coding agent" icon="robot" href="/integrations/mcp/overview">
    Give Claude Code, Cursor, or Codex your Bland account via MCP.
  </Card>

  <Card title="Agent quickstart" icon="bolt" href="/platform/agent-quickstart">
    Place a call, learn how it ended, and read the transcript, from an autonomous agent.
  </Card>
</CardGroup>