> For the complete documentation index, see [llms.txt](https://twentytwo.documentationai.com/llms.txt).
> Use it to discover all available pages before exploring further.

# Quick Start

The Twenty2 API lets you integrate AI voice calling directly into your own systems and workflows without using the Twenty2 dashboard.

This guide walks you through triggering your first outbound call and retrieving its result using the API.

## What you can do

<Columns cols="3">
  <Card title="Initiate a Call" href="/api-reference/initiate-call" icon="lucide-phone-call" horizontal="false" target="_self">
    Trigger an AI voice call to any phone number using a published assistant.
  </Card>

  <Card title="List Calls" href="/api-reference/list-calls" icon="list" horizontal="false" target="_self">
    Retrieve a list of outbound AI voice calls made from your workspace.
  </Card>

  <Card title="Get Call Detail" href="/api-reference/get-call-detail" icon="file-search2-icon" horizontal="false" target="_self">
    Fetch call status, transcripts, recordings, and output variables for a specific call.
  </Card>
</Columns>

All API requests are made to:

```bash
https://api.twentytwo.in/api
```

## How the API works

When you trigger a call via the API, the request is non-blocking. The endpoint immediately returns a `call_id` after the call is queued, while the actual phone call is placed asynchronously.

Use the returned `call_id` to track the call and retrieve results once it completes.

```text
POST /agent/trigger-outbound-call  →  returns call_id
GET  /call/detail?call_id=...      →  returns call result, transcript, and output parameters
```

> Calls are placed only between **9:00 AM and 9:00 PM IST**. Calls triggered outside this window are automatically queued and initiated at 9:00 AM the next day.

---

## Before you begin

Make sure you have:

- A Twenty2 account at [https://app.twentytwo.in](https://app.twentytwo.in)

- A published AI assistant from **My Assistants**

- A phone number purchased under **Manage Numbers**

- Sufficient wallet balance under **Billing → Add Balance**

---

## Step 1: Get your API credentials

Generate an API Key and Secret from:

**Profile → Integrations → Build with Twenty2 API → Create New**

Create your Basic Authentication token:

```bash
echo -n "your_api_key:your_api_key_secret" | base64
```

See the Authentication page for complete details.

---

## Step 2: Get your IDs

**Assistant ID**: Go to **My Assistants**, click the three-dot menu on your published assistant, and select **Copy Assistant ID**.

**Workspace ID**: Click the copy icon next to **Switch Workspace** at the bottom-left of the platform.

**Caller phone**: The number you purchased under **Manage Numbers**.

---

## Step 3: Trigger your first call

```bash
curl -X POST "https://api.twentytwo.in/api/agent/trigger-outbound-call" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64(api_key:api_key_secret)>" \
  -d '{
    "assistant_id": "<your_assistant_id>",
    "callee_phone": "9999999999",
    "caller_phone": "<your_caller_phone>",
    "input_parameters": {
      "customerName": "Rohit"
    }
  }'
```

Successful requests return a `call_id`:

```json
{
  "success": true,
  "statusCode": 201,
  "data": {
    "call_id": "6a329e7c5a54529ba7f0b4e6",
    "message": "Call queued successfully."
  }
}
```

---

## Step 4: Retrieve the call result

After the call completes, use the `call_id` to fetch the complete call details.

```bash
curl -X GET "https://api.twentytwo.in/api/call/detail?call_id=6a329e7c5a54529ba7f0b4e6" \
  -H "Authorization: Basic <base64(api_key:api_key_secret)>" \
  -H "x-workspace-id: <your_workspace_id>"
```

The response includes:

- Call status

- Duration

- Call cost

- Captured output parameters

- Recording URL

- Transcript URL

```json
{
  "success": true,
  "call": {
    "call_id": "6a329e7c5a54529ba7f0b4e6",
    "status": "completed",
    "duration_seconds": 94,
    "cost": "₹15.67",
    "output_parameters": {
      "interested": "yes",
      "callback_requested": "yes",
      "callback_time": "Tomorrow 11am"
    },
    "recording": {
      "url": "https://storage.twentytwo.in/recordings/...",
      "expires_at": "2025-01-25T10:01:34Z"
    }
  }
}
```

You have now successfully triggered an AI voice call and retrieved its results using the Twenty2 API.