API Documentation - AwajDigital Voice Broadcasting API

Authentication

All API requests require authentication using a Bearer token. You can obtain your API token from your dashboard account settings.

Important: Keep your API token secure and never share it publicly.

Example Request Headers

Authorization: Bearer your_api_token_here
Accept: application/json

Required Headers:

Authorization - Bearer token for authentication
Accept - Must be set to application/json to receive JSON responses
Content-Type - Required for POST requests, must be application/json

Download Postman Collection Import into Postman to test the API

POST /api/broadcasts/otp

Voice OTP Broadcast

Send OTP (One-Time Password) voice messages to a single phone number. The voice must contain at least one dynamic part with digit mode to read the OTP code.

Request Parameters

Parameter	Type	Required	Description
request_id	string	Yes	Unique request identifier (16-64 chars) to prevent duplicate requests. Use UUID or random string.
voice	string	Yes	Name of your approved voice with digit mode
sender	string	Yes	Your active caller sender number
phone_number	string	Yes	Single Bangladeshi phone number (01XXXXXXXXX format)
otp_code	string	Yes	OTP code (4-6 digits)

Request Example

curl -X POST https://api.awajdigital.com/api/broadcasts/otp \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "unique_request_id_123",
    "voice": "your_voice_name",
    "sender": "8801234567890",
    "phone_number": "019XXXXXXXX",
    "otp_code": "1234"
  }'

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/broadcasts/otp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_id: 'unique_request_id_123',
    voice: 'your_voice_name',
    sender: '8801234567890',
    phone_number: '019XXXXXXXX',
    otp_code: '1234'
  })
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function sendOtpBroadcast() {
  try {
    const response = await axios.post('https://api.awajdigital.com/api/broadcasts/otp', {
      request_id: 'unique_request_id_123',
      voice: 'your_voice_name',
      sender: '8801234567890',
      phone_number: '019XXXXXXXX',
      otp_code: '1234'
    }, {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

sendOtpBroadcast();

# Python with requests
import requests

def send_otp_broadcast():
    url = 'https://api.awajdigital.com/api/broadcasts/otp'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
    data = {
        'request_id': 'unique_request_id_123',
        'voice': 'your_voice_name',
        'sender': '8801234567890',
        'phone_number': '019XXXXXXXX',
        'otp_code': '1234'
    }

    try:
        response = requests.post(url, json=data, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

send_otp_broadcast()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/broadcasts/otp';
$token = 'your_api_token_here';

$data = [
    'request_id' => 'unique_request_id_123',
    'voice' => 'your_voice_name',
    'sender' => '8801234567890',
    'phone_number' => '019XXXXXXXX',
    'otp_code' => '1234'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "otp_api_1_your_voice_019XXXXXXXX",
    "status": "broadcasting",
    "createdAt": "2025-12-29T10:30:00.000Z"
  }
}

Note: Use a unique request_id for each request to prevent duplicate processing. Requests with the same request_id within 15 minutes will be rejected.

GET /api/broadcasts/:id/result

Get Broadcast Result

Retrieve the result of a broadcast. If the broadcast is still in progress, only status information is returned. If the broadcast is complete, detailed results for each phone number are included.

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The broadcast ID returned from broadcast creation

Request Example

curl -X GET https://api.awajdigital.com/api/broadcasts/123/result \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json"

// Browser JavaScript (Fetch API)
const broadcastId = 123;
const response = await fetch(`https://api.awajdigital.com/api/broadcasts/${broadcastId}/result`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getBroadcastResult(broadcastId) {
  try {
    const response = await axios.get(
      `https://api.awajdigital.com/api/broadcasts/${broadcastId}/result`,
      {
        headers: {
          'Authorization': 'Bearer your_api_token_here',
          'Accept': 'application/json'
        }
      }
    );

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getBroadcastResult(123);

# Python with requests
import requests

def get_broadcast_result(broadcast_id):
    url = f'https://api.awajdigital.com/api/broadcasts/{broadcast_id}/result'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_broadcast_result(123)

<?php
// PHP with cURL
$broadcastId = 123;
$url = "https://api.awajdigital.com/api/broadcasts/{$broadcastId}/result";
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Running Broadcast Response

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "api_1_voice_3",
    "status": "broadcasting",
    "listenerCount": 3,
    "completeCount": 1,
    "createdAt": "2025-12-30T10:00:00.000Z"
  },
  "isComplete": false,
  "message": "Broadcast is still in progress"
}

Completed Broadcast Response

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "api_1_voice_3",
    "status": "completed",
    "listenerCount": 3,
    "completeCount": 3,
    "createdAt": "2025-12-30T10:00:00.000Z"
  },
  "isComplete": true,
  "statusDistribution": {
    "pending": 0,
    "answered": 2,
    "notAnswered": 1,
    "rejected": 0,
    "busy": 0,
    "failed": 0,
    "unknown": 0
  },
  "results": [
    {
      "phoneNumber": "019XXXXXXXX",
      "status": "answered",
      "duration": 45
    },
    {
      "phoneNumber": "018XXXXXXXX",
      "status": "not_answered",
      "duration": null
    },
    {
      "phoneNumber": "017XXXXXXXX",
      "status": "answered",
      "duration": 30
    }
  ]
}

Note: The isComplete field indicates whether the broadcast has finished. Only when isComplete is true will the results array and statusDistribution be included in the response.

POST /api/broadcasts

Broadcast to Multiple Numbers

Send voice messages to multiple phone numbers in a single API call. Perfect for bulk announcements, notifications, or marketing campaigns.

Request Parameters

Parameter	Type	Required	Description
request_id	string	Yes	Unique request identifier (16-64 chars) to prevent duplicate requests. Use UUID or random string.
voice	string	Yes	Name of your approved voice
sender	string	Yes	Your active caller sender number
phone_numbers	array	Yes	Array of Bangladeshi phone numbers (01XXXXXXXXX format, max 999 numbers)

Request Example

curl -X POST https://api.awajdigital.com/api/broadcasts \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "unique_request_id_456",
    "voice": "your_voice_name",
    "sender": "8801234567890",
    "phone_numbers": ["019XXXXXXXX", "018XXXXXXXX", "017XXXXXXXX"]
  }'

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/broadcasts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_id: 'unique_request_id_456',
    voice: 'your_voice_name',
    sender: '8801234567890',
    phone_numbers: ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
  })
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function sendBroadcast() {
  try {
    const response = await axios.post('https://api.awajdigital.com/api/broadcasts', {
      request_id: 'unique_request_id_456',
      voice: 'your_voice_name',
      sender: '8801234567890',
      phone_numbers: ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
    }, {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

sendBroadcast();

# Python with requests
import requests

def send_broadcast():
    url = 'https://api.awajdigital.com/api/broadcasts'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
    data = {
        'request_id': 'unique_request_id_456',
        'voice': 'your_voice_name',
        'sender': '8801234567890',
        'phone_numbers': ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
    }

    try:
        response = requests.post(url, json=data, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

send_broadcast()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/broadcasts';
$token = 'your_api_token_here';

$data = [
    'request_id' => 'unique_request_id_456',
    'voice' => 'your_voice_name',
    'sender' => '8801234567890',
    'phone_numbers' => ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "api_1_your_voice_3",
    "status": "broadcasting",
    "createdAt": "2025-12-29T10:30:00.000Z"
  }
}

GET /api/broadcasts

List Broadcasts

Retrieve a list of all broadcasts created by the authenticated user. By default, returns broadcasts from the last 30 days. You can specify a custom date range (maximum 90 days).

Query Parameters

Parameter	Type	Required	Description
start_date	string	No	Start date in ISO 8601 format (e.g., 2025-01-01). Defaults to 30 days ago.
end_date	string	No	End date in ISO 8601 format (e.g., 2025-01-31). Defaults to today.

Important: The date range cannot exceed 90 days. If you need data for a longer period, make multiple requests with different date ranges.

Request Examples

curl -X GET https://api.awajdigital.com/api/broadcasts \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json"

curl -X GET "https://api.awajdigital.com/api/broadcasts?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json"

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/broadcasts', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getBroadcasts() {
  try {
    const response = await axios.get('https://api.awajdigital.com/api/broadcasts', {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getBroadcasts();

# Python with requests
import requests

def get_broadcasts():
    url = 'https://api.awajdigital.com/api/broadcasts'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_broadcasts()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/broadcasts';
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "broadcasts": [
    {
      "id": 123,
      "name": "api_1_voice_100",
      "status": "completed",
      "createdAt": "2025-01-15T10:30:00.000+06:00"
    },
    {
      "id": 124,
      "name": "api_1_voice_50",
      "status": "broadcasting",
      "createdAt": "2025-01-14T14:20:00.000+06:00"
    }
  ],
  "dateRange": {
    "startDate": "2025-01-01",
    "endDate": "2025-01-31"
  }
}

400 Bad Request - Date Range Too Large

Date range exceeds 90 days

{
  "success": false,
  "message": "Date range cannot exceed 90 days"
}

GET /api/voices

List Voices

Retrieve a list of all voices created by the authenticated user along with their approval status.

Request Example

curl -X GET https://api.awajdigital.com/api/voices \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json"

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/voices', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getVoices() {
  try {
    const response = await axios.get('https://api.awajdigital.com/api/voices', {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getVoices();

# Python with requests
import requests

def get_voices():
    url = 'https://api.awajdigital.com/api/voices'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_voices()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/voices';
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "voices": [
    {
      "id": 1,
      "name": "welcome_message",
      "status": "approved",
      "createdAt": "2025-12-01T10:00:00.000Z"
    },
    {
      "id": 2,
      "name": "otp_voice",
      "status": "pending",
      "createdAt": "2025-12-15T14:30:00.000Z"
    },
    {
      "id": 3,
      "name": "promo_announcement",
      "status": "rejected",
      "createdAt": "2025-12-20T09:15:00.000Z"
    }
  ]
}

Voice Status: Voices can have one of the following statuses: pending (under review), approved (ready to use), or rejected (not approved).

GET /api/senders

List Senders

Retrieve a list of all caller sender numbers associated with the authenticated user's account along with their status.

Request Example

curl -X GET https://api.awajdigital.com/api/senders \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json"

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/senders', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getSenders() {
  try {
    const response = await axios.get('https://api.awajdigital.com/api/senders', {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getSenders();

# Python with requests
import requests

def get_senders():
    url = 'https://api.awajdigital.com/api/senders'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_senders()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/senders';
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "senders": [
    {
      "id": 1,
      "callingNumber": "8801234567890",
      "status": "active"
    },
    {
      "id": 2,
      "callingNumber": "8809876543210",
      "status": "active"
    },
    {
      "id": 3,
      "callingNumber": "8805555555555",
      "status": "inactive"
    }
  ]
}

Sender Status: Senders can have one of the following statuses: active (ready to use) or inactive (temporarily disabled). Only active senders can be used for broadcasts.

POST /api/surveys

Create Survey

Create and start a voice survey campaign to collect responses from multiple phone numbers. The survey uses a published template with interactive questions that recipients can respond to using their phone keypad.

Request Parameters

Parameter	Type	Required	Description
request_id	string	Yes	Unique request identifier (16-64 chars) to prevent duplicate requests. Use UUID or random string.
template_name	string	Yes	Name of your published survey template. Template must be in "published" status.
sender	string	Yes	Your active caller sender number (must be assigned to your account and active).
phone_numbers	array	Yes	Array of Bangladeshi phone numbers (01XXXXXXXXX format, max 999 numbers). No duplicates allowed.
metadata	object	No	Custom data to associate with the survey. Will be returned in results and webhook payload.
webhook_url	string	No	URL to receive webhook notification when survey completes.

Request Example

curl -X POST https://api.awajdigital.com/api/surveys \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "unique_survey_request_123",
    "template_name": "customer_satisfaction_survey",
    "sender": "8801234567890",
    "phone_numbers": ["019XXXXXXXX", "018XXXXXXXX", "017XXXXXXXX"],
    "metadata": { "campaign_id": "summer2025", "customer_segment": "premium" },
    "webhook_url": "https://your-domain.com/webhook"
  }'

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/surveys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_id: 'unique_survey_request_123',
    template_name: 'customer_satisfaction_survey',
    sender: '8801234567890',
    phone_numbers: ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX'],
    metadata: { campaign_id: 'summer2025', customer_segment: 'premium' },
    webhook_url: 'https://your-domain.com/webhook'
  })
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function createSurvey() {
  try {
    const response = await axios.post('https://api.awajdigital.com/api/surveys', {
      request_id: 'unique_survey_request_123',
      template_name: 'customer_satisfaction_survey',
      sender: '8801234567890',
      phone_numbers: ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX'],
      metadata: { campaign_id: 'summer2025', customer_segment: 'premium' },
      webhook_url: 'https://your-domain.com/webhook'
    }, {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createSurvey();

# Python with requests
import requests

def create_survey():
    url = 'https://api.awajdigital.com/api/surveys'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
    data = {
        'request_id': 'unique_survey_request_123',
        'template_name': 'customer_satisfaction_survey',
        'sender': '8801234567890',
        'phone_numbers': ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX'],
        'metadata': { 'campaign_id': 'summer2025', 'customer_segment': 'premium' },
        'webhook_url': 'https://your-domain.com/webhook'
    }

    try:
        response = requests.post(url, json=data, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

create_survey()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/surveys';
$token = 'your_api_token_here';

$data = [
    'request_id' => 'unique_survey_request_123',
    'template_name' => 'customer_satisfaction_survey',
    'sender' => '8801234567890',
    'phone_numbers' => ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX'],
    'metadata' => ['campaign_id' => 'summer2025', 'customer_segment' => 'premium'],
    'webhook_url' => 'https://your-domain.com/webhook'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "survey": {
    "id": 456,
    "name": "api_survey_1_customer_satisfaction_survey_3",
    "status": "ready",
    "totalCount": 3,
    "createdAt": "2025-12-30T10:00:00.000Z",
    "metadata": { "campaign_id": "summer2025", "customer_segment": "premium" }
  }
}

Note: The survey will be created with status "ready" and will automatically start broadcasting to the provided phone numbers. Use the request_id to prevent duplicate survey creation within 15 minutes.

Prerequisites: Before creating a survey, ensure you have: (1) A published survey template created in your dashboard, (2) An active sender number assigned to your account, and (3) Sufficient balance to cover the survey calls.

GET /api/surveys/:id/result

Get Survey Result

Retrieve the results of a voice survey campaign. The response includes survey metadata, call status distribution, and detailed results for each phone number including the keys pressed by recipients during the survey.

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The survey ID returned from survey creation.

Request Example

curl -X GET https://api.awajdigital.com/api/surveys/456/result \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json"

// Browser JavaScript (Fetch API)
const surveyId = 456;
const response = await fetch(`https://api.awajdigital.com/api/surveys/${surveyId}/result`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getSurveyResult(surveyId) {
  try {
    const response = await axios.get(
      `https://api.awajdigital.com/api/surveys/${surveyId}/result`,
      {
        headers: {
          'Authorization': 'Bearer your_api_token_here',
          'Accept': 'application/json'
        }
      }
    );

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getSurveyResult(456);

# Python with requests
import requests

def get_survey_result(survey_id):
    url = f'https://api.awajdigital.com/api/surveys/{survey_id}/result'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_survey_result(456)

<?php
// PHP with cURL
$surveyId = 456;
$url = "https://api.awajdigital.com/api/surveys/{$surveyId}/result";
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

In-Progress Survey Response

{
  "success": true,
  "survey": {
    "id": 456,
    "name": "api_survey_1_customer_satisfaction_survey_3",
    "status": "broadcasting",
    "totalCount": 3,
    "completeCount": 1,
    "createdAt": "2025-12-30T10:00:00.000Z",
    "metadata": { "campaign_id": "summer2025", "customer_segment": "premium" }
  },
  "isComplete": false,
  "statusDistribution": {
    "pending": 2,
    "answered": 1,
    "not_answered": 0,
    "failed": 0
  },
  "numbers": [
    {
      "number": "019XXXXXXXX",
      "status": "pending",
      "duration": null,
      "pressedKeys": []
    },
    {
      "number": "018XXXXXXXX",
      "status": "answered",
      "duration": 45,
      "pressedKeys": ["1", "5"]
    },
    {
      "number": "017XXXXXXXX",
      "status": "pending",
      "duration": null,
      "pressedKeys": []
    }
  ]
}

Completed Survey Response

{
  "success": true,
  "survey": {
    "id": 456,
    "name": "api_survey_1_customer_satisfaction_survey_3",
    "status": "completed",
    "totalCount": 3,
    "completeCount": 3,
    "createdAt": "2025-12-30T10:00:00.000Z",
    "metadata": { "campaign_id": "summer2025", "customer_segment": "premium" }
  },
  "isComplete": true,
  "statusDistribution": {
    "pending": 0,
    "answered": 2,
    "not_answered": 1,
    "failed": 0
  },
  "numbers": [
    {
      "number": "019XXXXXXXX",
      "status": "answered",
      "duration": 52,
      "pressedKeys": ["2", "4", "1"]
    },
    {
      "number": "018XXXXXXXX",
      "status": "answered",
      "duration": 45,
      "pressedKeys": ["1", "5"]
    },
    {
      "number": "017XXXXXXXX",
      "status": "not_answered",
      "duration": null,
      "pressedKeys": []
    }
  ]
}

Note: The isComplete field indicates whether the survey has finished (status is "completed" or "cancelled"). The pressedKeys array contains the digits pressed by the recipient in response to survey questions. The statusDistribution shows the count of calls in each status: pending, answered, not_answered, or failed.

Survey Response Data: Each number in the results includes the call status, duration (in seconds), and the keys pressed by the recipient. Use this data to analyze survey responses and calculate metrics like response rates, average call duration, and answer distributions.

Survey Webhooks

When a survey completes, a POST request is sent to your webhook URL with the survey results.

Webhook Payload

{
  "survey_id": 456,
  "metadata": { "campaign_id": "summer2025", "customer_segment": "premium" },
  "results": [
    {
      "phone_number": "019XXXXXXXX",
      "status": "answered",
      "response": "1",
      "responses": ["1", "5"]
    },
    {
      "phone_number": "018XXXXXXXX",
      "status": "answered",
      "response": "2",
      "responses": ["2", "4", "1"]
    }
  ]
}

Payload Fields

Field	Type	Description
survey_id	integer	The unique identifier of the survey
metadata	object	Custom metadata passed when creating the survey (optional)
results	array	Array of result objects for each phone number

Result Object Fields

Field	Type	Description
phone_number	string	The phone number of the respondent
status	string	Call status: `pending`, `answered`, `not_answered`, or `failed`
response	string	The first key pressed by the respondent (only if status is `answered`)
responses	array	All keys pressed during the survey (only if status is `answered`)

Note: The webhook is sent once when the survey status becomes "completed". The response and responses fields are only present when the call status is answered.

Error Responses

The API uses standard HTTP status codes and returns error details in JSON format.

401 Unauthorized

Invalid or missing API token

{
  "success": false,
  "message": "Unauthorized"
}

400 Bad Request - OTP Validation

Voice must have at least one dynamic part with digit mode

{
  "success": false,
  "message": "Voice must have at least one dynamic part with digit mode for OTP broadcast"
}

400 Bad Request - Duplicate Numbers

Duplicate phone numbers found in the request

{
  "success": false,
  "message": "Duplicate phone number found",
  "duplicated_number": "019XXXXXXXX"
}

402 Payment Required

Insufficient balance to process the broadcast

{
  "success": false,
  "message": "Insufficient balance"
}

403 Forbidden

Voice not found, not approved, or sender not active

{
  "success": false,
  "message": "Voice not found or not approved"
}

409 Conflict

Duplicate request - request_id already used within 15 minutes

{
  "success": false,
  "message": "Request already processed"
}

404 Not Found

Broadcast or survey not found or access denied

{
  "success": false,
  "message": "Broadcast not found"
}

500 Internal Server Error

Server error occurred while processing the request

{
  "success": false,
  "message": "Failed to create OTP broadcast"
}

Survey-Specific Errors

403 Forbidden - Template Not Found

Survey template not found or not in published status

{
  "success": false,
  "message": "Template not found or not published"
}

403 Forbidden - Sender Not Found

Sender number not found or not active

{
  "success": false,
  "message": "Sender not found or not active"
}