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

# Calls API — Retrieve and Initiate Outbound Calls

> REST API endpoints for retrieving individual call records, dispositions, durations, recordings, and initiating one-off outbound calls via VInfer Neuron.

Every conversation Neuron conducts — whether as part of a campaign or triggered as a one-off outbound call — is recorded as a call object. Call records contain the outcome disposition, duration, language used, a link to the audio recording, and (if NeuronLens processing was requested) a pointer to the transcript job. The Calls API lets you retrieve, filter, and initiate these calls programmatically.

***

## List Calls

<code>GET /calls</code>

Returns a paginated list of call records across your workspace. You can filter by campaign, date range, disposition, or language to scope results to exactly what your integration needs.

### Query Parameters

<ParamField query="campaign_id" type="string">
  Filter calls to those belonging to a specific campaign. Omit to return calls across all campaigns.
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 datetime — return calls that started on or after this time. Example: `2024-01-01T00:00:00Z`.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 datetime — return calls that started on or before this time.
</ParamField>

<ParamField query="disposition" type="string">
  Filter by call disposition. One of: `interested`, `not_interested`, `callback`, `not_reachable`, `dnd`, `escalated`.
</ParamField>

<ParamField query="language" type="string">
  Filter by BCP-47 language code, e.g. `hi-IN`, `ta-IN`, `en-IN`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results per page. Maximum `100`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip. Use with `limit` to paginate.
</ParamField>

### Example Request

```bash theme={null}
curl "https://api.vinfer.ai/v1/calls?campaign_id=cmp_4Rv8sT1wX&disposition=escalated&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "cal_9Hm3kP7qZ",
      "campaign_id": "cmp_4Rv8sT1wX",
      "contact": {"phone": "+919876543210", "name": "Priya Sharma"},
      "status": "completed",
      "disposition": "escalated",
      "duration_seconds": 142,
      "language": "hi-IN",
      "started_at": "2024-02-01T09:14:03Z",
      "ended_at": "2024-02-01T09:16:25Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}
```

***

## Get Call Details

<code>GET /calls/\{id}</code>

Returns the full record for a single call, including a signed recording URL and a pointer to the NeuronLens transcript job if the call was processed.

### Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the call.
</ResponseField>

<ResponseField name="campaign_id" type="string">
  The ID of the parent campaign. `null` for calls initiated directly via `POST /calls`.
</ResponseField>

<ResponseField name="contact" type="object">
  The contact who was called.

  <Expandable title="Contact fields">
    <ResponseField name="contact.phone" type="string">
      Phone number in E.164 format.
    </ResponseField>

    <ResponseField name="contact.name" type="string">
      Contact display name.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="string">
  Current call status: `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="disposition" type="string">
  The outcome disposition set at the end of the call. One of: `interested`, `not_interested`, `callback`, `not_reachable`, `dnd`, `escalated`. `null` if the call is still `in_progress`.
</ResponseField>

<ResponseField name="duration_seconds" type="integer">
  Total call duration in seconds, measured from when the contact answered to when the call ended. `0` for calls that were not connected.
</ResponseField>

<ResponseField name="language" type="string">
  BCP-47 language code used for this call (e.g., `hi-IN`).
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp of when the call was initiated (dial attempt began).
</ResponseField>

<ResponseField name="ended_at" type="string">
  ISO 8601 timestamp of when the call ended. `null` if still `in_progress`.
</ResponseField>

<ResponseField name="transcript_job_id" type="string">
  The NeuronLens job ID for this call's transcript, if transcription was requested. Pass this to `GET /transcription/{job_id}` to retrieve results. `null` if not processed.
</ResponseField>

<ResponseField name="recording_url" type="string">
  A signed URL pointing to the call audio recording. **Expires in 1 hour** — fetch and cache if you need to display or process the audio. `null` if recording was not enabled or the call was not connected.
</ResponseField>

### Example Request

```bash theme={null}
curl https://api.vinfer.ai/v1/calls/cal_9Hm3kP7qZ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "id": "cal_9Hm3kP7qZ",
  "campaign_id": "cmp_4Rv8sT1wX",
  "contact": {
    "phone": "+919876543210",
    "name": "Priya Sharma"
  },
  "status": "completed",
  "disposition": "escalated",
  "duration_seconds": 142,
  "language": "hi-IN",
  "started_at": "2024-02-01T09:14:03Z",
  "ended_at": "2024-02-01T09:16:25Z",
  "transcript_job_id": "job_2Kn7wR4pM",
  "recording_url": "https://recordings.vinfer.ai/signed/cal_9Hm3kP7qZ?token=eyJ...&expires=1706783785"
}
```

<Warning>
  Recording URLs expire after 1 hour. If your application needs to store or display recordings, download the audio to your own storage within that window. Do not cache the signed URL itself — request a fresh URL by calling this endpoint again.
</Warning>

***

## Initiate a Single Call

<code>POST /calls</code>

Triggers a single outbound call to one contact immediately, outside of any campaign. Useful for one-off transactional calls — for example, sending a verification callback or a single appointment reminder.

### Request Body

<ParamField body="phone" type="string" required>
  The destination phone number in E.164 format. Example: `+919876543210`.
</ParamField>

<ParamField body="name" type="string" required>
  The contact's name, used for personalization within the script.
</ParamField>

<ParamField body="script_id" type="string" required>
  The ID of the voice script to run. The script must be configured for single-call use.
</ParamField>

<ParamField body="language" type="string" required>
  BCP-47 language code for the call. Example: `en-IN`.
</ParamField>

<ParamField body="metadata" type="object">
  Optional key-value pairs passed into the script context as custom variables. For example, `{"appointment_date": "3rd February", "doctor_name": "Dr. Kapoor"}`.
</ParamField>

### Example Request

```bash theme={null}
curl https://api.vinfer.ai/v1/calls \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "name": "Priya Sharma",
    "script_id": "scr_appt_reminder",
    "language": "en-IN",
    "metadata": {
      "appointment_date": "3rd February",
      "doctor_name": "Dr. Kapoor",
      "clinic": "Sunrise Health"
    }
  }'
```

### Example Response

```json theme={null}
{
  "id": "cal_6Xb1nQ8rJ",
  "campaign_id": null,
  "contact": {"phone": "+919876543210", "name": "Priya Sharma"},
  "status": "in_progress",
  "disposition": null,
  "language": "en-IN",
  "started_at": "2024-02-01T11:05:44Z",
  "ended_at": null,
  "transcript_job_id": null,
  "recording_url": null
}
```

<Note>
  Use `GET /calls/{id}` to poll for the call's final status and disposition after initiating it, or register a `call.completed` webhook to receive the result automatically without polling.
</Note>

***

## Get Call Transcript

<code>GET /calls/\{id}/transcript</code>

Returns the NeuronLens transcript for a specific call, if transcription was enabled and processing has completed. This is a convenience endpoint that proxies the transcript from the NeuronLens job associated with the call.

### Example Request

```bash theme={null}
curl https://api.vinfer.ai/v1/calls/cal_9Hm3kP7qZ/transcript \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "call_id": "cal_9Hm3kP7qZ",
  "job_id": "job_2Kn7wR4pM",
  "status": "completed",
  "language": "hi-IN",
  "duration_seconds": 142,
  "transcript": [
    {
      "speaker": "agent",
      "text": "Namaste, Priya ji. Main VInfer ki taraf se baat kar raha hoon. Kya aap abhi baat kar sakte hain?",
      "start_time": 0.4,
      "end_time": 5.1,
      "confidence": 0.97
    },
    {
      "speaker": "customer",
      "text": "Haan, bataiye.",
      "start_time": 5.9,
      "end_time": 7.2,
      "confidence": 0.95
    },
    {
      "speaker": "agent",
      "text": "Aapka loan renewal ka time aa gaya hai. Kya aap is baare mein baat karna chahenge?",
      "start_time": 7.6,
      "end_time": 13.0,
      "confidence": 0.96
    },
    {
      "speaker": "customer",
      "text": "Haan, mujhe kisi se baat karni hai. Please mujhe connect karein.",
      "start_time": 13.5,
      "end_time": 18.2,
      "confidence": 0.94
    }
  ],
  "summary": "Customer expressed interest in loan renewal and requested escalation to a human agent.",
  "sentiment": {
    "overall": 0.42,
    "by_speaker": {
      "agent": 0.65,
      "customer": 0.38
    }
  }
}
```

<Note>
  If transcription has not completed yet, the response returns `{"status": "processing"}` with no `transcript` array. Poll again in a few seconds, or use `GET /transcription/{job_id}` for more detailed job status information.
</Note>