Skip to main content
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

​
campaign_id
string
Filter calls to those belonging to a specific campaign. Omit to return calls across all campaigns.
​
from
string
ISO 8601 datetime — return calls that started on or after this time. Example: 2024-01-01T00:00:00Z.
​
to
string
ISO 8601 datetime — return calls that started on or before this time.
​
disposition
string
Filter by call disposition. One of: interested, not_interested, callback, not_reachable, dnd, escalated.
​
language
string
Filter by BCP-47 language code, e.g. hi-IN, ta-IN, en-IN.
​
limit
integer
default:"20"
Number of results per page. Maximum 100.
​
offset
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

​
id
string
Unique identifier for the call.
​
campaign_id
string
The ID of the parent campaign. null for calls initiated directly via POST /calls.
​
contact
object
The contact who was called.
​
status
string
Current call status: in_progress, completed, or failed.
​
disposition
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.
​
duration_seconds
integer
Total call duration in seconds, measured from when the contact answered to when the call ended. 0 for calls that were not connected.
​
language
string
BCP-47 language code used for this call (e.g., hi-IN).
​
started_at
string
ISO 8601 timestamp of when the call was initiated (dial attempt began).
​
ended_at
string
ISO 8601 timestamp of when the call ended. null if still in_progress.
​
transcript_job_id
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.
​
recording_url
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

​
phone
string
required
The destination phone number in E.164 format. Example: +919876543210.
​
name
string
required
The contact’s name, used for personalization within the script.
​
script_id
string
required
The ID of the voice script to run. The script must be configured for single-call use.
​
language
string
required
BCP-47 language code for the call. Example: en-IN.
​
metadata
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.