Calls API — Retrieve and Initiate Outbound Calls

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

GET /calls 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

string

Filter calls to those belonging to a specific campaign. Omit to return calls across all campaigns.

string

ISO 8601 datetime — return calls that started on or after this time. Example: 2024-01-01T00:00:00Z.

string

ISO 8601 datetime — return calls that started on or before this time.

string

Filter by call disposition. One of: interested, not_interested, callback, not_reachable, dnd, escalated.

string

Filter by BCP-47 language code, e.g. hi-IN, ta-IN, en-IN.

integer

default:"20"

Number of results per page. Maximum 100.

integer

default:"0"

Number of results to skip. Use with limit to paginate.

Example Request

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

Example Response

{
  "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

GET /calls/{id} 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

string

Unique identifier for the call.

string

The ID of the parent campaign. null for calls initiated directly via POST /calls.

object

The contact who was called.

Show Contact fields

string

Phone number in E.164 format.

string

Contact display name.

string

Current call status: in_progress, completed, or failed.

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.

integer

Total call duration in seconds, measured from when the contact answered to when the call ended. 0 for calls that were not connected.

string

BCP-47 language code used for this call (e.g., hi-IN).

string

ISO 8601 timestamp of when the call was initiated (dial attempt began).

string

ISO 8601 timestamp of when the call ended. null if still in_progress.

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.

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.

Example Request

curl https://api.vinfer.ai/v1/calls/cal_9Hm3kP7qZ \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "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"
}

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.

Initiate a Single Call

POST /calls 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

string

required

The destination phone number in E.164 format. Example: +919876543210.

string

required

The contact’s name, used for personalization within the script.

string

required

The ID of the voice script to run. The script must be configured for single-call use.

string

required

BCP-47 language code for the call. Example: en-IN.

object

Optional key-value pairs passed into the script context as custom variables. For example, {"appointment_date": "3rd February", "doctor_name": "Dr. Kapoor"}.

Example Request

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

{
  "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
}

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.

Get Call Transcript

GET /calls/{id}/transcript 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

curl https://api.vinfer.ai/v1/calls/cal_9Hm3kP7qZ/transcript \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "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
    }
  }
}

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.

Overview

Neuron API

NeuronLens API

Calls API — Retrieve and Initiate Outbound Calls

List Calls

Query Parameters

Example Request

Example Response

Get Call Details

Response Fields

Example Request

Example Response

Initiate a Single Call

Request Body

Example Request

Example Response

Get Call Transcript

Example Request

Example Response

​List Calls

​Query Parameters

​Example Request

​Example Response

​Get Call Details

​Response Fields

​Example Request

​Example Response

​Initiate a Single Call

​Request Body

​Example Request

​Example Response

​Get Call Transcript

​Example Request

​Example Response

List Calls

Query Parameters

Example Request

Example Response

Get Call Details

Response Fields

Example Request

Example Response

Initiate a Single Call

Request Body

Example Request

Example Response

Get Call Transcript

Example Request

Example Response