The Xcall API is built from the ground up as a REST API and can interact with any HTTP client in any programming language. This documentation provides instructions on how to quickly integrate our voice services into your application. It is easy to understand and provides code samples to point you in the right direction.

Get Authenticated

You can obtain XCall API credentials form our web platform in 2 quick steps:

Step 1. Visit https://xcall.com.ng to create a user account. If you already have an Xcall user account, you can skip this step.

Step 2: Login using the user account from step 1.

• Navigate to Settings --> API Credentials
• Enter your App name to identify your credential, and click on "Generate".
• Click on "Save" to confirm and save the credentials.

Request Headers

These are the standard request headers that are needed when authenticating with the API. The API endpoints accepts json content types for requests and will produce a json response. You shoud specify "Content-Type: application/json" and "Accept: application/json" in the header section of API requests.

Voice Messaging

Creating Outbound Calls

This API endpoint sends automated calls to one or multiple phone numbers and plays a recorded audio message or text-to-speech message.

Request Parameters

Request Example

• JSON
• cURL
• PHP

                             POST /v3/call HTTP/1.1 Host: https://api.xcall.com.ng Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ== 
Content-Type: application/json Accept: application/json {
    "from":"234703XXXXXXX",
    "to":[
        "234810XXXXXXX",
        "234803XXXXXXX"
    ],
    "ttsMsg": "Hello Jane! This call is from ABC Logistics. We want to notify you that you have a parcel to pickup at our office. Please come with a valid ID.  
Thank you.",
    "ttsVoice": "uk-male"
}
                            
                        

                             curl -X POST \
  -H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    
        "from":"234703XXXXXXX",
        "to":[
            "234810XXXXXXX",
            "234803XXXXXXX"
        ],
        "ttsMsg": "Hello Jane! This call is from ABC Logistics. We want to notify you that you have a parcel to pickup at our office. Please come with a valid 
ID.  Thank you.",
        "ttsVoice": "uk-male"
    }' "https://api.xcall.com.ng/v3/call"
                            
                        

                             <?php /* Define sender ID $from= "234703XXXXXXX"; /* populate destination array. */ 
$to = []; $to[]= "234810XXXXXXX"; $to[]= "234803XXXXXXX"; /* If message is text to speech, define its parameters */ $ttsMsg= "Hello Jane! This call is from ABC 
Logistics. We want to notify you that you have a parcel to pickup at our office. Please come with a valid ID.  Thank you."; $ttsVoice= "uk-male"; /*if message 
is recorded audio, define its URL */ $audioFileUrl= "http://www.example.com/sounds/audio.mp3"; $requestData = array(
    "broadcastName" => $name,
    "ttsMsg" => $ttsMsg,
    "ttsVoice" => $ttsVoice,
    "audioFileUrl" => $audioFileUrl,
    "to" => $to,
    "from" => $from,
    "startTime" => "567889900" /* Unix timestamp to begin the calls. Defaut is to begin calls immediately. */ ); /* convert requestData to json format */ 
$requestData = json_encode($requestData); /* Make API request */ $curl = curl_init(); curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.xcall.com.ng/v3/call",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $requestData,
  CURLOPT_HTTPHEADER => array(
    "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "content-type: application/json",
    "accept: application/json"
  ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?> 
                                
                            
                        

Response Parameters

Creating Outbound IVR Calls

This API endpoint makes outbound interactive voice calls to one or multiple phone numbers. You can send automated phone calls to multiple recipients, ask questions, and record responses in real time.

Creating an IVR broadcast is in two steps:

• Step 1: You create an IVR template.
• Step 2: You create outbound calls using the template from step 1.

Step 1: Creating an IVR Template

An IVR Template is the major element of an IVR broadcast in our system. It defines the call flow logic for an IVR call.

To create an IVR template, logon to the client web portal. Navigate to Settings → IVR Templates → New IVR Template and follow the instructions on the page. Note the ID of the template you have created. You can use a single template for multiple IVR broadcasts.

Step 2: Create broadcast using template from step 1

Simply make an api request using the template ID from step 1 above. The request parameters are described below.

Request Parameters

Request Example

• JSON
• cURL
• PHP

                             POST /v3/ivr HTTP/1.1 Host: https:api.xcall.com.ng Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ== 
Content-Type: application/json Accept: application/json {
    "broadcastName": "Test call",
    "templateId": "123DG2345D7BB178",
    "from":"2349081235467",
    "messages":[
        {
            "to":"2347031234567",
            "customData":{
                "name": "John",
                "appointment": "September 12, 2019"
            }
        },
        {
            "to":"2348151234568",
            "customData":{
                "name": "Mary",
                "appointment": "September 10, 2019"
            }
        }
    ],
    "startTime": "56789467820",
    "maxRetries": "3",
    "waitTime": "5",
    "notifyUrl": "https://www.mydomain.com/voice/process_callbacks"
}
 
                            
                        

                             curl -X POST \
  -H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    
        "templateId": "123DG2345D7BB178",
        "from":"2349081235467",
        "messages":[
            {
                "to":"2347031234567",
                "customData":{
                    "name": "John",
                    "appointment": "September 12, 2019"
                }
            },
            {
                "to":"2348151234568",
                "customData":{
                    "name": "Mary",
                    "appointment": "September 10, 2019"
                }
            },
        ],
        "startTime": "56789467820",
        "maxRetries":"3",
        "waitTime": "5",
        "notifyUrl": "https://www.mydomain.com/voice/process_callbacks"
    }' "https://api.xcall.com.ng/ivr"
                            
                        

                             <?php /* Define sender ID $from= "2348191234567"; $templateId= "1475"; /* populate 
messages. */ $messages = []; $messages[]= array(
    "to"=> 2347031234567",
    "customData"=> array(
        "name": "John",
        "appointment": "September 11"
    ); $messages[]= array(
    "to"=> 2348151234568",
    "customData"=> array(
        "name": "Mary",
        "appointment": "September 14
    ); $requestData = array(
    "broadcastName" => $name,
    "from" => $from
    "templateId" => $templateId,
    "messages" => $messages
    "startTime" => "56789467820",
    "maxRetries" => "3",
    waitTime" => "5",
    "notifyUrl" => "https://www.mydomain.com/voice/process_callbacks" ); /* convert requestData to json format */ $requestData = json_encode($requestData); /* 
Make API request */ $curl = curl_init(); curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.xcall.com.ng/api/ivr",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $requestData,
  CURLOPT_HTTPHEADER => array(
    "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "content-type: application/json",
    "accept: application/json"
  ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?> 
                                
                            
                        

Response Parameters

Receiving Voice Delivery Reports (via webhook)

You can receive delivery reports for voice broadcasts, outbound IVR, and survey campaigns automatically when the campaign completes. Specify a webhook URL (using the notifyUrl parameter) when you create the broadcast, or register a webhook URL on your account for the events below. Xcall will POST a JSON payload to that URL when the campaign finishes.

For campaigns with fewer than 500 contacts, both events are dispatched. For larger campaigns, only voice.campaign.delivery.summary is dispatched — the full per-contact CDR remains available on demand via /v3/voiceReport.

Each webhook request includes the following HTTP header, which you can use to verify authenticity:

x-xcall-signature: <your-webhook-token>

Event: voice.campaign.delivery.report

Full delivery report, containing one call record per destination. Sent for campaigns with fewer than 500 contacts.

Payload Example

 {
  "event": "voice.campaign.delivery.report",
  "timestamp": "2026-09-29T09:02:47Z",
  "data": {
    "broadcastId": "31940",
    "name": "apiTest",
    "type": "simple broadcast",
    "dateCreated": "2026-09-29T08:11:04Z",
    "startTime": "2026-09-29T08:15:00Z",
    "endTime": "2026-09-29T09:02:47Z",
    "status": "completed",
    "destinations": 2,
    "msgFile": "tts_audio_4n4h3k5t8y9b.mp3",
    "cdr": [
      {
        "sessionId": 6231407,
        "from": "2348037891009",
        "to": "2348130429229",
        "sentAt": "2026-09-29T08:15:02Z",
        "result": "failed",
        "disposition": "ringing, no answer",
        "answerTime": null,
        "duration": 0
      },
      {
        "sessionId": 6231408,
        "from": "2348037891009",
        "to": "2348187957011",
        "sentAt": "2026-09-29T08:15:03Z",
        "result": "success",
        "disposition": "Answered",
        "answerTime": "2026-09-29T08:15:09Z",
        "duration": 22
      }
    ]
  }
}

Payload Fields

Call Record Fields (each element of data.cdr)

Event: voice.campaign.delivery.summary

Aggregate summary of the campaign. Sent for all completed campaigns, regardless of size. Because the payload is compact and does not grow with campaign size, this is the recommended event for integrations that monitor campaign outcomes at scale.

Payload Example

 {
  "event": "voice.campaign.delivery.summary",
  "timestamp": "2026-09-29T09:02:47Z",
  "data": {
    "broadcastId": "31940",
    "name": "apiTest",
    "type": "simple broadcast",
    "dateCreated": "2026-09-29T08:11:04Z",
    "startTime": "2026-09-29T08:15:00Z",
    "endTime": "2026-09-29T09:02:47Z",
    "status": "completed",
    "destinations": 1200,
    "msgFile": "tts_audio_4n4h3k5t8y9b.mp3",
    "summary": {
      "destinations": 1200,
      "dialed": 1195,
      "answered": 890,
      "failed": 305,
      "pending": 5,
      "dispositions": {
        "answered": 890,
        "unreachable": 120,
        "ringing, no answer": 185
      }
    },
    "detailEndpoint": "/v3/voiceReport"
  }
}

Payload Fields

The top-level event, timestamp, and all data.* fields up to and including data.msgFile are identical to the full report event. The differences are the fields below.

Receiving Webhooks (PHP Example)

The example below reads the raw JSON body, inspects the event field, and dispatches to the appropriate handler. You can subscribe to one or both events from your account's webhook settings.

• PHP

                         <?php /* Read the raw JSON body from the incoming POST. */ $raw = 
file_get_contents("php://input"); $payload = json_decode($raw, true); if (!is_array($payload) || empty($payload["event"])) {
    http_response_code(400);
    exit("Bad payload");
}
$event = $payload["event"]; $data = $payload["data"]; /* Respond 2xx promptly. Queue the data for async processing if your
   handler needs more than a couple of seconds. */ if ($event === "voice.campaign.delivery.summary") {
    /* ---- Summary event (always fired) ---- */
    $broadcastId = $data["broadcastId"];
    $summary = $data["summary"];
    error_log(sprintf(
        "Campaign %s finished: %d answered, %d failed, %d pending",
        $broadcastId,
        $summary["answered"],
        $summary["failed"],
        $summary["pending"]
    ));
    /* Per-contact detail is available on demand: */
    /* $detailUrl = "https://api.xcall.com.ng" . $data["detailEndpoint"]; */
} elseif ($event === "voice.campaign.delivery.report") {
    /* ---- Full report event (campaigns under 500 contacts) ---- */
    $broadcastId = $data["broadcastId"];
    $cdr = $data["cdr"];
    foreach ($cdr as $record) {
        error_log(sprintf(
            " %s -> %s: %s (%s)",
            $record["from"],
            $record["to"],
            $record["result"],
            $record["disposition"]
        ));
    }
} else {
    /* Unknown event; log and ignore. */
    error_log("Unhandled webhook event: " . $event);
}
/* Respond 200 so Xcall records the delivery as successful. */ http_response_code(200); echo "OK"; ?>                        
                    

Delivery Guarantees and Retries

• Xcall considers a webhook delivered when your endpoint responds with an HTTP 2xx status within 30 seconds.
• If delivery fails, Xcall retries with exponential backoff: approximately 5 minutes, 15 minutes, 1 hour, 6 hours, and 24 hours after the initial attempt.
• After the final retry, the webhook is marked as failed and no further attempts are made.
• To avoid duplicate processing, treat each webhook as idempotent, keyed on the pair event + data.broadcastId.

Notes

• When both events fire for the same campaign, they arrive within a few seconds of each other. Ordering between the two events is not guaranteed.
• If you set the notifyUrl parameter when creating the broadcast, both events are delivered to that URL. Otherwise, each event is delivered to the webhook URL registered on your account for that event.
• All timestamps in the payload are RFC 3339 UTC.
• The detailEndpoint field is a relative path. Prepend the API host https://api.xcall.com.ng to build the absolute URL.

Getting Voice Delivery Reports (via query)

This API endpoint returns the delivery report for a completed voice broadcast, outbound IVR, or survey campaign. The report includes a summary of the campaign and an array of per-contact call records. The endpoint supports pagination so large campaigns can be retrieved in batches.

Delivery reports are available for completed campaigns only.

Request Parameters

Request Example

• JSON
• cURL
• PHP

POST /v3/voiceReport HTTP/1.1 Host: https://api.xcall.com.ng Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ== 
Content-Type: application/json Accept: application/json {
    "broadcastId": "5128",
    "limit": "25",
    "offset": "0"
}
                        
                    

curl -X POST \
  -H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "broadcastId": "5128",
        "limit": "25",
        "offset": "0"
   }' "https://api.xcall.com.ng/v3/voiceReport"
                        
                    

<?php /* Define broadcast ID */ $broadcastId = "5128"; /* Build request payload */ 
$requestData = array(
    "broadcastId" => $broadcastId,
    "limit" => "25",
    "offset" => "0" ); /* Convert requestData to json format */ $requestData = json_encode($requestData); /* Make API request */ $curl = curl_init(); 
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.xcall.com.ng/v3/voiceReport",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $requestData,
  CURLOPT_HTTPHEADER => array(
    "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "content-type: application/json",
    "accept: application/json"
  ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?>                        
                    

Response on Success

 HTTP/1.1 200 OK Content-Type: application/json {
  "result": "OK",
  "report": {
    "broadcastId": "5128",
    "name": "October Promo",
    "type": "simple broadcast",
    "dateCreated": "2026-09-29T08:11:04Z",
    "startTime": "2026-09-29T08:15:00Z",
    "endTime": "2026-09-29T09:02:47Z",
    "status": "completed",
    "destinations": 1200,
    "msgFile": "promo_oct.mp3",
    "cdr": [
      {
        "sessionId": 918273,
        "from": "07030000000",
        "to": "2348031234567",
        "sentAt": "2026-09-29T08:15:02Z",
        "result": "success",
        "disposition": "answered",
        "answerTime": "2026-09-29T08:15:09Z",
        "duration": 22
      },
      {
        "sessionId": 918274,
        "from": "07030000000",
        "to": "2348039876543",
        "sentAt": "2026-09-29T08:15:03Z",
        "result": "failed",
        "disposition": "ringing, no answer",
        "answerTime": null,
        "duration": 0
      }
    ],
    "pagination": {
      "limit": 25,
      "offset": 0,
      "total": 1200,
      "returned": 2,
      "hasMore": true
    }
  }
}

Response Parameters

Call Record Fields (each element of report.cdr)

Pagination Fields (report.pagination)

Pagination Example

To retrieve all 1,200 call records of a campaign with a page size of 100, request the following offsets in sequence: 0, 100, 200, …, 1100. Stop when pagination.hasMore is false. For example, the last page would be requested with:

 {
    "broadcastId": "5128",
    "limit": 100,
    "offset": 1100
}

Error Responses

SMS Messaging

Send simple text message

This API enables you to send a text message (same message) to one or multiple recipients.

Request Parameters

Request Example

• JSON
• cURL
• PHP

                             POST /v3/sms HTTP/1.1 Host: https://api.xcall.com.ng Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ== 
Content-Type: application/json Accept: application/json {
    "from":"XYZ",
    "to":[
        "2347031234567",
        "2348057654321"
    ],
    "smsText": "This is a test SMS",
    "notifyUrl": "http://mydomain.com/sms/report"
}
                            
                        

                             curl -X POST \
  -H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    
        "from":"XYZ",
        "to":[
            "2347031234567",
            "2348057654321"
        ],
        "smsText": "This is a test SMS",
        "notifyUrl": "http://mydomain.com/sms/report"
    }' "https://api.xcall.com.ng/v3/sms"
                            
                        

                             <?php /* Define sender ID $from= "XYZ"; /* populate destination array. */ $to = 
array("2347031234567", "2348057654321"); $smsText = "This is a test SMS"; $notifyUrl= "http://mydomain.com/sms/report"; $requestData = array(
    "from" => $from,
    "to" => $to,
    "smsText" => $smsText,
    "notifyUrl" => $notifyUrl,
    "sendAt" => "567889900" /* Unix timestamp to send text message. Defaut is to begin immediately. */ ); /* convert requestData to json format */ $requestData 
= json_encode($requestData); /* Make API request */ $curl = curl_init(); curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.xcall.com.ng/v3/sms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $requestData,
  CURLOPT_HTTPHEADER => array(
    "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "content-type: application/json",
    "accept: application/json"
  ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?> 
                                
                            
                        

 HTTP/1.1 200 OK Content-Type: application/json {
    "result":"OK",
    "description":"Request accepted",
    "broadcastId":"1315145",
    "units_used":"2",
    "credit_balance":"1216.5",
    "messages":[
      {
         "to":"2347031234567",
         "status": "PENDING",
         "messageId": "145698"
      },
      {
         "to":"2348057654321",
         "status": "PENDING",
         "messageId": "605569"
      }
    ]
}

Response Parameters

Get SMS Credit Balance

This endpoint allows an authenticated user to retrieve their current SMS credit balance.
Each user is limited to 100 requests per day to this endpoint. Once the daily limit is reached, subsequent requests to this endpoint will be rejected until the next day (00:00 UTC).

The get_sms_balance.php endpoint should be used sparingly — ideally for dashboards or occasional syncs.
It is not recommended to use this endpoint to check for credit balance before every sms send request. Instead, you can rely on the 'credit_balance' field in send responses to cache the lastest known balance and avoid extra API calls.

Sample Request

GET URL: https://api.xcall.com.ng/v3/get_balance.php

This endpoint does not require any body parameters. Ensure that standard authentication headers are included in the request.

Sample Responses

Successful Response

 Content-Type: application/json {
    "result":"OK",
    "description":"Request successful",
    "user":"john@abc.com",
    "credit_balance":"1520.75"
}

Rate Limit Exceeded

 Content-Type: application/json {
    "result":"ERROR",
    "user":"john@abc.com",
    "description":"Rate limit exceeded. You have reached your 100 requests per day quota."
}