Place a Click to Call

GET POST /api/voice/v1/click2call

Places one Click to Call from one of your account's DIDs. Requires a key scoped to voice.click2call or all. A 202 means the call was accepted — it is billed later, after the CDR, and only if it connects. Only one Click to Call may be in flight per account.

Parameters

Request example

curl -X POST "https://cpaas.studio/api/voice/v1/click2call" \
  -H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 9d1f-4a2c-agent-42" \
  -d "did_id=812" \
  -d "agent_number=9526071065" \
  -d "customer_number=9812345678" \
  -d "reference=lead-4471"

<?php
$ch = curl_init('https://cpaas.studio/api/voice/v1/click2call');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Idempotency-Key: 9d1f-4a2c-agent-42',
        'Content-Type: application/json',
    ],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'did_id' => 812,
        'agent_number' => '9526071065',
        'customer_number' => '9812345678',
        'reference' => 'lead-4471',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Success response (data)

{
    "uid": "CC7Q2M4X8A1B",
    "event_id": "c2c-AB12CD34EF",
    "reference": "lead-4471",
    "status": "submitted",
    "disposition": null,
    "agent_number": "9526071065",
    "customer_number": "9812345678",
    "ring_time": 20,
    "duration_seconds": null,
    "billsec": null,
    "billing_status": "pending",
    "billable_units": null,
    "recording_available": false,
    "submitted_at": "2026-09-11T10:20:30+00:00",
    "answered_at": null,
    "completed_at": null,
    "created_at": "2026-09-11T10:20:30+00:00"
}

Errors

Notes

• A 202 means accepted, not connected and not billed. Billing is charged once, after the CDR, only on a call that actually connected — poll the status endpoint for the outcome.
• What a call costs depends on your assigned plan's pulse setting: per call ("full call"), or per 30/60-second pulse of connected time (billsec — ring time is never charged). A plan on unlimited (validity) billing is not charged per call.
• On a plan with overdraft enabled, quota is not checked before dialing, because the amount is not known until the call ends — it may go negative, and the shortfall is settled automatically the next time a plan is assigned. Without overdraft, a request is refused up front once the quota is used up.
• The number of Click to Call requests that may be in flight per account at once is set by your assigned plan (falling back to a platform default). A request over that limit is refused with 409 C2C_CONCURRENT_CALL — the attempt is still recorded and still has a uid, so it appears in your logs.
• An optional Idempotency-Key request header replays the original call on an identical retry within 24 hours; a different body under the same key is a conflict, never a silent no-op.
• One request is one call. There is no batching, no scheduling, and no recipient list.
• Ring time is a fixed platform setting (20 seconds) and is not settable per call. It is returned in every response for reference, but sending a ring_time field is rejected rather than ignored, so a value you set can never silently fail to apply.