Voice call report and refunds by API (answered, charged, refunded)

To get the result of a voice campaign sent through the Fast2SMS API, call GET https://www.fast2sms.com/dev/voice/report?request_id=V.... It returns the campaign status, how many calls were answered, the amount held, charged and refunded, and, with numbers=1, the result of every number: status, duration, pulses, charge and the key pressed. This guide explains each field, when the money settles, and gives code in cURL, PHP, Python and Node.js.

Get the campaign summary

  1. Use the request_id from the send reply

    When you send with /dev/voice/bulk, the reply has a request_id that starts with V, for example VdQkbYrvgtOo2nG. Store it.

  2. Call the report API

    curl -G "https://www.fast2sms.com/dev/voice/report" \
      -H "authorization: YOUR_API_KEY" \
      --data-urlencode "request_id=VdQkbYrvgtOo2nG"
  3. Read the summary

    {"return":true,"request_id":"VdQkbYrvgtOo2nG","campaign_name":"Festive Offer Call - Pune",
     "type":"simple","status":"completed","schedule_time":"2026-10-09 11:05:00",
     "numbers":60,"dialled":60,"answered":38,"pulses":66,
     "amount_held":30,"amount_charged":16.5,"amount_refunded":13.5,"completed":true}
  4. Compare with the panel

    The same campaign is in Delivery Report, Voice Report. Click it to see the status breakdown, Total Pulses, Cost per Pulse, Charged, Refunded and each receiver.

    Voice Reports campaign Festive Offer Call - Pune with 60 calls: 38 answered, 12 no answer, 5 busy, 3 failed, 2 DND, total pulses 66, charged 16.50 and refunded 13.50, and receiver rows with status, description, duration, pulses and charge
    The panel shows the same totals as the report API.

Summary fields

Field Meaning
type simple, dtmf (Key Press) or callpatch
status scheduled, submitting, running, paused, completed, stopped, failed or cancelled
numbers Valid numbers in the campaign
dialled Numbers processed so far
answered Calls that were answered
pulses Total pulses charged
amount_held Rupees held from your wallet when the campaign was accepted
amount_charged Final charge. null until the campaign is settled
amount_refunded null until settled, then 0 until the refund is credited, then the refunded amount
completed true once the campaign is settled and the charges are final

Get the result of every number

Add numbers=1. Results come 1,000 rows per page; use page to go through them.

curl -G "https://www.fast2sms.com/dev/voice/report" \
  -H "authorization: YOUR_API_KEY" \
  --data-urlencode "request_id=VdQkbYrvgtOo2nG" \
  --data-urlencode "numbers=1" --data-urlencode "page=1"
{"return":true,"request_id":"VdQkbYrvgtOo2nG","status":"completed","completed":true,
 "page":1,"last_page":1,
 "data":[
  {"mobile":"9999999999","status":"answered","duration":23,"agent_duration":0,"pulses":2,"charge":0.5,
   "dtmf":null,"agent_number":null,"start_time":"2026-10-09 11:06:09","end_time":"2026-10-09 11:06:32","reason":"Call answered"},
  {"mobile":"8888888888","status":"no_answer","duration":0,"agent_duration":0,"pulses":0,"charge":0,
   "dtmf":null,"agent_number":null,"start_time":null,"end_time":null,"reason":"Switched off or not reachable"}]}

The summary fields are in this reply too; the example above is shortened.

Per-number status Meaning Charged?
queued Not called yet (shown as Pending in the panel) Not yet
answered The call was answered Yes, by the pulse
no_answer Rang but not answered, or switched off No
busy The line was busy No
failed Invalid number, network error or other failure No
dnd On DND, not called by the operator No
blacklisted On your voice blacklist, not called No

reason has a plain explanation, such as “Call answered”, “Number busy”, “Call rejected”, “Switched off or not reachable”, “DND number: not called by operator”, “Not sent: outside calling hours (10 AM – 9 PM)” or “No result from operator”. For Key Press, dtmf is the key pressed. For Call Patch, agent_number and agent_duration show who answered and how long they talked.

When charges and refunds become final

  • At send, the estimated cost is held from your wallet (amount_held).
  • When the operator’s report for the campaign is in, it is settled: completed becomes true and amount_charged is the sum of the answered calls.
  • The difference is credited back about an hour later as “Unanswered Voice Call Refund”. Then amount_refunded shows the amount.
  • Numbers with no result from the operator are not charged.
  • Cancelled campaigns, and campaigns that could not start, are refunded in full at once.

Every refund also appears in Voice Report, Refund in the panel, month by month, with an Export CSV button.

Voice Refund Report for November 2026 with Total Calls 160, Amount Debited 150, Amount Refunded 78.25, Net Amount 71.75, a debit and refund chart and campaign rows
The Refund page lists debits and refunds for each campaign.

Code examples

PHP: wait until completed, then read every number

<?php
function voiceReport(string $requestId, int $page = 0): array {
    $q = ["request_id" => $requestId];
    if ($page > 0) { $q["numbers"] = 1; $q["page"] = $page; }
    $ch = curl_init("https://www.fast2sms.com/dev/voice/report?" . http_build_query($q));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ["authorization: YOUR_API_KEY"],
        CURLOPT_TIMEOUT        => 30,
    ]);
    $data = json_decode(curl_exec($ch), true) ?? [];
    curl_close($ch);
    return $data;
}

$summary = voiceReport("VdQkbYrvgtOo2nG");
if (($summary["completed"] ?? false) === true) {
    $page = 1;
    do {
        $res = voiceReport("VdQkbYrvgtOo2nG", $page);
        foreach ($res["data"] ?? [] as $row) {
            echo $row["mobile"] . " " . $row["status"] . " Rs " . $row["charge"] . PHP_EOL;
        }
        $page++;
    } while ($page <= ($res["last_page"] ?? 1));
} else {
    echo "Status: " . ($summary["status"] ?? $summary["message"] ?? "unknown");
}

Python

import requests

URL = "https://www.fast2sms.com/dev/voice/report"
HEADERS = {"authorization": "YOUR_API_KEY"}
request_id = "VdQkbYrvgtOo2nG"

summary = requests.get(URL, headers=HEADERS, params={"request_id": request_id}, timeout=30).json()
print(summary.get("status"), "answered:", summary.get("answered"), "charged:", summary.get("amount_charged"))

if summary.get("completed"):
    page, last = 1, 1
    while page <= last:
        res = requests.get(URL, headers=HEADERS,
                           params={"request_id": request_id, "numbers": 1, "page": page}, timeout=30).json()
        for row in res.get("data", []):
            print(row["mobile"], row["status"], row["reason"], row["charge"])
        last = res.get("last_page", 1)
        page += 1

Node.js

const params = new URLSearchParams({ request_id: "VdQkbYrvgtOo2nG", numbers: "1", page: "1" });
const res = await fetch(`https://www.fast2sms.com/dev/voice/report?${params}`, {
  headers: { authorization: process.env.FAST2SMS_API_KEY },
});
const data = await res.json();
if (data.return === true) {
  console.log(data.status, "answered:", data.answered);
  for (const row of data.data || []) console.log(row.mobile, row.status, row.dtmf, row.charge);
} else {
  console.log(data.message);
}

Report API or webhook?

Check the report every few minutes until completed is true. If you want each number’s result pushed to you instead, create a Voice webhook in Webhook, Voice. It sends one request per number after the campaign is settled, with status, duration, pulses, amount, key pressed and agent. No webhook is sent for blacklisted or DND numbers. See webhooks in Fast2SMS.

Common problems and fixes

“Invalid request_id.” (HTTP 404)

The ID is wrong or belongs to another account. Use the V ID from the send reply with the same account’s API key.

amount_charged is null

The campaign is not settled yet. Calls may still be running, or the operator report has not come in. Check again later.

amount_refunded is 0 but completed is true

The refund is credited about an hour after settling. Check again after an hour.

status is paused

Either calling hours ended at 9 PM while numbers were still left, or your wallet balance went below zero. Recharge if the balance is the cause, and contact support if the campaign does not continue.

status is failed

The campaign could not run, for example because a voice file was not approved by the operator. The full amount is refunded. The panel shows the reason in the campaign’s Delivery Details.

Frequently asked questions

How do I know which numbers answered my voice call?

Call the report API with numbers=1, or download the campaign from Voice Report. Answered numbers have the status answered.

Am I charged for unanswered voice calls?

No. Only answered calls are charged. The held amount for the rest is refunded automatically.

How long does the voice call refund take?

About 1 hour after the campaign finishes. If it takes longer, contact support with the Request ID.

What is a pulse?

The billing unit for call time. A call’s duration is rounded up to whole pulses. At the time of writing a pulse is 15 seconds.

Can I download the report as Excel?

Yes. In Voice Report, each campaign row has a Download button for an .xlsx file.