curl --request POST \
  --url https://api.voice.mergenlab.ai/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "agent_id": "agt_credfin_dpd_8_30_m",
  "to": "+9198XXXXXX01",
  "variables": {
    "case_id": "CF-LN-208841",
    "borrower_first_name": "मोहित",
    "call_stage": "DPD 8-30",
    "emi_amount": 4200,
    "original_due_date": "2026-09-25",
    "dpd": 17,
    "late_charges": 374,
    "total_overdue": 4574,
    "max_ptp_days": 3,
    "min_part_payment": 1500
  },
  "metadata": {
    "loan_id": "CF-LN-208841",
    "borrower_ref": "BR-55102"
  }
}
'

{
  "id": "call_9f1c2a7e4b3d4c0e8a6b5d2f1e0c9b8a",
  "agent_id": "agt_credfin_dpd_8_30_m",
  "call_type": "ai_voice",
  "to": "+9198XXXXXX01",
  "status": "completed",
  "scheduled_for": null,
  "attempts_count": 1,
  "outcome": "promise_to_pay",
  "summary": "The borrower confirmed the overdue amount of INR 4,574 and promised to pay in full by Friday.",
  "duration_sec": 61.5,
  "billable_minutes": 2,
  "cost": {
    "amount_micros": 9180000,
    "currency": "INR",
    "status": "final"
  },
  "has_recording": true,
  "has_transcript": true,
  "metadata": {
    "loan_id": "CF-LN-208841",
    "borrower_ref": "BR-55102"
  },
  "created_at": "2026-10-12T05:30:00.120Z",
  "updated_at": "2026-10-12T05:37:42.906Z",
  "ended_at": "2026-10-12T05:31:14.880Z"
}

Calls

Create an AI voice call or a human call

Creates a call. The body depends on call_type:

ai_voice (default when call_type is left out): a voice agent calls to. The agent must belong to your account and be active. Variables are the agent’s defaults merged with yours (values are sent to the agent as strings); every variable in the agent’s required_variables must end up set, and the agent’s opening message must render without unresolved {{placeholders}}. The call is queued and dialled as soon as the agent’s calling window and your concurrency allow; outside the window it is accepted with scheduled_for set to the next window start. Answer: 202 with status: "queued".
human: rings agent_phone and to and bridges them from caller ID from. Checked in this order: idempotent replay, human calling enabled, human calling hours, caller ID, daily cap, one live call per agent_phone. Answer: 202 with status: "dialling", agent_id: null and human.status: "initiated" (it moves on within a second; follow it with call.status_changed webhooks or GET /v1/calls/{id}).

call_type: "reachability" is rejected here (422); use POST /v1/reachability-checks.

POST

calls

curl --request POST \
  --url https://api.voice.mergenlab.ai/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "agent_id": "agt_credfin_dpd_8_30_m",
  "to": "+9198XXXXXX01",
  "variables": {
    "case_id": "CF-LN-208841",
    "borrower_first_name": "मोहित",
    "call_stage": "DPD 8-30",
    "emi_amount": 4200,
    "original_due_date": "2026-09-25",
    "dpd": 17,
    "late_charges": 374,
    "total_overdue": 4574,
    "max_ptp_days": 3,
    "min_part_payment": 1500
  },
  "metadata": {
    "loan_id": "CF-LN-208841",
    "borrower_ref": "BR-55102"
  }
}
'

{
  "id": "call_9f1c2a7e4b3d4c0e8a6b5d2f1e0c9b8a",
  "agent_id": "agt_credfin_dpd_8_30_m",
  "call_type": "ai_voice",
  "to": "+9198XXXXXX01",
  "status": "completed",
  "scheduled_for": null,
  "attempts_count": 1,
  "outcome": "promise_to_pay",
  "summary": "The borrower confirmed the overdue amount of INR 4,574 and promised to pay in full by Friday.",
  "duration_sec": 61.5,
  "billable_minutes": 2,
  "cost": {
    "amount_micros": 9180000,
    "currency": "INR",
    "status": "final"
  },
  "has_recording": true,
  "has_transcript": true,
  "metadata": {
    "loan_id": "CF-LN-208841",
    "borrower_ref": "BR-55102"
  },
  "created_at": "2026-10-12T05:30:00.120Z",
  "updated_at": "2026-10-12T05:37:42.906Z",
  "ended_at": "2026-10-12T05:31:14.880Z"
}

Authorizations

Authorization

string

header

required

Authorization: Bearer vg_live_<32 hex characters>. Keys are issued by Mergen admins and shown once. Missing or invalid key: 401 unauthorized. Suspended account: 403 tenant_suspended.

Headers

Idempotency-Key

string

required

1 to 64 characters, unique per logical request (a UUID works). Same key and body again: 200 with the current resource. Same key, different body: 409 idempotency_conflict. Missing: 422 validation_error.

Required string length: 1 - 64

Body

application/json

AI voice call
Human call

POST /v1/calls body, chosen by call_type: leave call_type out (or send "ai_voice") for an AI voice call, send "human" for a human call. Exactly one of the two shapes matches any valid body.

call_type works as the discriminator, but it is not declared with the OpenAPI discriminator keyword: in OpenAPI 3.1 a discriminator property must always be present, while this API defaults a missing call_type to ai_voice. Generated clients may always send call_type; "ai_voice" is accepted.

agent_id

string

required

An active agent of your account (GET /v1/agents).

Required string length: 1 - 128

Example:

"agt_credfin_dpd_8_30_m"

string

required

Customer number (Indian; see "Phone numbers").

Required string length: 1 - 32

Example:

"+9198XXXXXX01"

call_type

string

Optional; ai_voice is the default.

Allowed value: "ai_voice"

from

string

Preferred caller number: one of your active numbers (GET /v1/numbers), E.164. Each call gets one of your numbers connected for voice AI that is free at dial time (a number carries one call at a time): this one when it is free, else the free number used least recently. When every such number is on a call, the call waits in the queue (estimated_start_at). Leave it out to prefer the agent's default number. A number that is not one of your active voice numbers is 422 caller_id_not_owned; an account with no number connected for voice AI is 422 no_voice_ai_number.

Required string length: 1 - 32

Example:

"+9180XXXXXX79"

variables

object

Values for the agent's variables, merged over the agent's defaults. Names are letters, digits and underscores (start with a letter or _, at most 64 characters). Every name in the agent's required_variables must end up set.

Show child attributes

metadata

object

Your own JSON object, returned unchanged (at most 4 KB as JSON). Mergen never reads it.

schedule_at

string<date-time>

Earliest time to dial (ISO 8601 with Z or an offset), at most 7 days ahead. A time in the past means now. The calling window still applies.

Response

Replay of an earlier request with the same Idempotency-Key and body. Returns the call's current state.

A call of any type. human is present only on human calls; reachability_check_id and reachability only on reachability dials; broadcast_id and broadcast only on voice broadcast dials; campaign_id, campaign_contact_id and campaign_step_id only on calls a campaign placed (absent, not null, on other calls). outcome is the agent's outcome for AI calls, the terminal human.status for human calls and the result for reachability and broadcast dials.

string

required

call_ + 32 hex characters.

Example:

"call_9f1c2a7e4b3d4c0e8a6b5d2f1e0c9b8a"

agent_id

string | null

required

The voice agent; null for human calls, reachability dials and broadcast dials.

Example:

"agt_credfin_dpd_8_30_m"

call_type

enum<string>

required

ai_voice: a voice agent calls the customer. human: your agent and the customer bridged by phone. reachability: one dial of a reachability check. broadcast: one dial of a voice broadcast.

Available options:

ai_voice,

human,

reachability,

broadcast

string

required

Customer number, E.164.

Example:

"+9198XXXXXX01"

status

enum<string>

required

queued (waiting for its first dial, a scheduled time, the calling window or a retry), dialling (an attempt is live), then terminal completed (a person was connected), no_answer, busy, failed, canceled. An AI call goes back to queued while a retry is pending.

Available options:

queued,

dialling,

completed,

no_answer,

busy,

failed,

canceled

scheduled_for

string<date-time> | null

required

When a queued call will be dialled (a future schedule_at, the next calling window start, or the retry time). null when it is due now or the call is not queued.

attempts_count

integer

required

Dial attempts made so far.

Required range: x >= 0

outcome

string | null

required

AI calls: the outcome reported by the agent for the latest attempt (agent-specific, for example promise_to_pay, no_commitment, callback_requested), null until analysed. Human calls: the terminal human.status. Reachability and broadcast dials: the dial result.

Example:

"promise_to_pay"

summary

string | null

required

Short summary of the conversation (AI calls), null otherwise or until analysed.

duration_sec

number | null

required

Seconds of the latest attempt: conversation length for AI calls, talk time (agent and customer bridged) for human calls, seconds held after the answer for reachability dials, seconds from the answer to the hangup for broadcast dials. null until known.

Example:

61.5

billable_minutes

integer

required

Billable minutes summed over the call's attempts (each connected attempt rounded up to whole minutes; 0 when not connected).

Required range: x >= 0

cost

object

required

Your cost summed over the call's attempts; pending while the call is not over or any attempt's cost is not final.

Show child attributes

has_recording

boolean

required

has_transcript

boolean

required

Always false for human calls, reachability dials and broadcast dials.

metadata

object | null

required

The metadata you sent (reachability dials carry the number's items_metadata, broadcast dials the broadcast's and the item's metadata), or null.

created_at

string<date-time>

required

updated_at

string<date-time>

required

ended_at

string<date-time> | null

required

When the call reached a terminal status.

from

string

Only on AI calls, once dialled: the number the latest attempt dialled from (given at dial time from your free numbers; see from on the request).

Example:

"+9180XXXXXX79"

estimated_start_at

string<date-time> | null

When a call that is waiting for a free line is expected to start. An estimate; null once the call is placed.

human

object

Live state of a human call (human on CallView; only on human calls).

Show child attributes

reachability_check_id

string

The check this dial belongs to (reachability dials only).

Example:

"rch_4e7b1c9d2a3f4e5b8c6d7a8b9c0d1e2f"

reachability

object

One dial of a reachability check (reachability on CallView; only on reachability calls). The call's status for a ring-check dial: dialling while live, completed only when the customer picked up (answered), no_answer for ringing (not answered) and switched_off, busy for busy, failed for invalid and failed, canceled for canceled.

Show child attributes

broadcast_id

string

The voice broadcast this dial belongs to (broadcast dials only).

Example:

"vbc_7c1e9a3b5d2f4e6a8b0c2d4e6f8a1b3c"

broadcast

object

One dial of a voice broadcast (broadcast on CallView; only on broadcast calls). The call's status: dialling while live, completed for played and partial (a person heard the message; priced), no_answer for voicemail and no_answer, busy, failed for failed and invalid, canceled.

Show child attributes

disposition

null | object

Human calls only (absent on others); null until your agent sets one (PUT /v1/calls/{id}/disposition).

Show child attributes

campaign_id

string

The campaign that placed this call (campaign calls only; GET /v1/calls?campaign_id=).

Example:

"cmp_3b9e1f7a2c4d4e6f8a0b1c2d3e4f5a6b"

campaign_contact_id

string

The campaign record (rec_...) the call was for (campaign calls only).

Example:

"rec_1a2b3c4d5e6f40718293a4b5c6d7e8f9"

campaign_step_id

string

Which attempt of the record's ladder the call is, as attempt_<number> (campaign calls only).

Example:

"attempt_2"

Calls

Reachability and missed calls

Campaigns

Payments and do-not-call

Power dialer

Web sessions

Account

Webhooks

Create an AI voice call or a human call

Authorizations

Headers

Body

Response