Create Survey

POST /api/surveys

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" }
  }
}