POST

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

mode: "ring" makes a ring check: ring_sec applies, and hold_sec, answer_message and machine_detection must not be sent (any value, null included, is a 422 validation_error with one issue per field: not used when mode is ring). ring_sec in an answer check is a 422 (only used when mode is ring).

​
numbers
string[]
required

Customer numbers (Indian; see "Phone numbers"). Bad and repeated numbers become skipped results.

Required array length: 1 - 1000 elements
Required string length: 1 - 32
​
mode
enum<string>

answer (default): wait for a pick-up, hold the line hold_sec seconds and hang up. ring: hang up as soon as the phone has rung ring_sec seconds; nobody needs to pick up (the customer sees a missed call).

Available options:
answer,
ring
​
from
string

Preferred caller ID: one of your active voice numbers. Default: your reachability default caller ID, else your human-calling default caller ID, else your oldest active number. Each call of the check uses it when it is free, else a free number (see "Phone numbers"); each result's from shows the one used.

Required string length: 1 - 32
​
hold_sec
integer

Answer check only. Seconds to hold the line after a person answers. Default: your account setting (12 unless changed).

Required range: 5 <= x <= 30
​
ring_sec
integer

Ring check only. Seconds the phone rings before we hang up. Default: your account setting (2 unless changed). Free unless the customer picks up within ring_sec; then priced as a connected call.

Required range: 1 <= x <= 10
​
ring_timeout_sec
integer
default:45

Seconds to wait for an answer (answer check) or for the phone to start ringing (ring check).

Required range: 10 <= x <= 60
​
machine_detection
boolean
default:true

Answer check only. Answering-machine detection (machines are hung up at once and reported as voicemail).

​
answer_message
string | null

Answer check only. Text spoken once when a person answers, before the hold (recommended, for example who is calling). Default: your account setting. Blank means none.

Maximum string length: 200
​
max_attempts
integer
default:1

Dials per number. Retried results only; answer check no_answer and busy, ring check busy and switched_off.

Required range: 1 <= x <= 3
​
retry_delays_min
integer[]

Minutes before retry 1 and 2 (the last value is reused; 0 retries at once).

Required array length: 1 - 2 elements
Required range: 0 <= x <= 1440
​
metadata
object

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

​
items_metadata
object

Per-number metadata keyed by number (in any accepted format), each at most 1 KB as JSON. Copied to that number's result and to the metadata of its dials.

Response

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

​
id
string
required

rch_ + 32 hex characters.

Example:

"rch_4e7b1c9d2a3f4e5b8c6d7a8b9c0d1e2f"

​
status
enum<string>
required

running (dialling), waiting_window (outside your calling hours, numbers wait), queued (paused on our side, for example reachability was disabled after creation), then completed or canceled.

Available options:
queued,
running,
waiting_window,
completed,
canceled
​
mode
enum<string>
required

answer (default): wait for a pick-up, hold the line hold_sec seconds and hang up. ring: hang up as soon as the phone has rung ring_sec seconds; nobody needs to pick up (the customer sees a missed call).

Available options:
answer,
ring
​
from
string
required

Caller ID used, E.164.

​
hold_sec
integer | null
required

null for a ring check.

​
ring_sec
integer | null
required

null for an answer check.

​
ring_timeout_sec
integer
required
​
machine_detection
boolean
required

false for a ring check.

​
answer_message
string | null
required

null for a ring check.

​
max_attempts
integer
required
​
retry_delays_min
integer[]
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
completed_at
string<date-time> | null
required

When the batch finished (also set on a canceled check once its last dial ends).

​
canceled_at
string<date-time> | null
required
​
counts
object
required

Numbers per result (computed when read). total = numbers sent, duplicates and invalid inputs included.

​
cost
object
required

Your cost (never the provider's). pending until every part of the cost is known, then final. no_rule: no pricing is configured for your account yet (amount_micros is null). Integer INR micros (1,000,000 = INR 1).

​
metadata
object
required

The metadata you sent; {} when none.

​
campaign_id
string

Only on a check a campaign placed (a ring_check step; lists show those with include_campaign=true); absent otherwise, as on a CallView. Also in the reachability.* webhooks.

​
campaign_contact_id
string

The campaign contact (cct_...) the check was placed for; with campaign_id only.

​
campaign_step_id
string

The campaign step that placed it; with campaign_id only.