# 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

```bash
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"
  }'
```

```javascript
// 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);
```

```javascript
// 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
# 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
// 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

```json
{
  "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.
:::

:::tip[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.
:::