Survey Results

Retrieve and analyze survey responses.

Get Survey Responses

Retrieve individual survey responses for a campaign.

warning

The campaign must be of type Survey. If the specified campaign is not a Survey campaign, the API returns a 400 Bad Request error.

GET /api/v1/survey-results

Query Parameters

Parameter	Type	Required	Description
campaignId	UUID	Yes	Campaign ID
phoneNumber	string	No	Filter by phone number
externalUserId	string	No	Filter by external user ID (e.g., order ID)
startDate	datetime	No	Filter from date
endDate	datetime	No	Filter to date
selectedOptionIndex	integer	No	Filter by selected option
page	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 20, max: 100)

Response

{
  "results": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "campaignId": "660e8400-e29b-41d4-a716-446655440001",
      "phoneNumber": "38970123456",
      "externalUserId": "order_12345",
      "selectedOptionText": "Very Satisfied",
      "selectedOptionIndex": 0,
      "trackingData": null,
      "respondedAt": "2024-01-15T14:30:00Z"
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440004",
      "campaignId": "660e8400-e29b-41d4-a716-446655440001",
      "phoneNumber": "38970654321",
      "externalUserId": "order_12346",
      "selectedOptionText": "Satisfied",
      "selectedOptionIndex": 1,
      "trackingData": null,
      "respondedAt": "2024-01-15T14:35:00Z"
    }
  ],
  "totalCount": 85,
  "page": 1,
  "pageSize": 20,
  "totalPages": 5
}

Response Fields

Field	Type	Description
id	UUID	Survey response ID
campaignId	UUID	Campaign ID
phoneNumber	string	Respondent's phone
externalUserId	string	External user ID from the original message (e.g., order ID)
selectedOptionText	string	Text of selected option
selectedOptionIndex	integer	Index of selected option (0-based)
trackingData	string	Optional tracking data
respondedAt	datetime	When response was submitted

Example

cURL

# Get all responses for a campaign
curl -X GET "https://api.transformify.mk/api/v1/survey-results?campaignId=660e8400-e29b-41d4-a716-446655440001" \
  -H "X-API-Key: your-api-key"

# Filter by external user ID (e.g., order ID)
curl -X GET "https://api.transformify.mk/api/v1/survey-results?campaignId=660e8400-e29b-41d4-a716-446655440001&externalUserId=order_12345" \
  -H "X-API-Key: your-api-key"

# Filter by date range
curl -X GET "https://api.transformify.mk/api/v1/survey-results?campaignId=660e8400-e29b-41d4-a716-446655440001&startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: your-api-key"

# Filter by option index (matches optionValue from template creation)
curl -X GET "https://api.transformify.mk/api/v1/survey-results?campaignId=660e8400-e29b-41d4-a716-446655440001&selectedOptionIndex=3" \
  -H "X-API-Key: your-api-key"

JavaScript

const campaignId = '660e8400-e29b-41d4-a716-446655440001';

const params = new URLSearchParams({
  campaignId,
  page: '1',
  pageSize: '50'
});

const response = await fetch(
  `https://api.transformify.mk/api/v1/survey-results?${params}`,
  {
    headers: { 'X-API-Key': 'your-api-key' }
  }
);

const data = await response.json();
console.log(`Total responses: ${data.totalCount}`);

Python

import requests

campaign_id = '660e8400-e29b-41d4-a716-446655440001'

response = requests.get(
    'https://api.transformify.mk/api/v1/survey-results',
    headers={'X-API-Key': 'your-api-key'},
    params={
        'campaignId': campaign_id,
        'page': 1,
        'pageSize': 50
    }
)

data = response.json()
print(f"Total responses: {data['totalCount']}")

---

Get Survey Summary

Get aggregated statistics for a survey campaign.

GET /api/v1/survey-results/{campaignId}/summary

Path Parameters

Parameter	Type	Description
campaignId	UUID	Campaign ID

Response

{
  "campaignId": "660e8400-e29b-41d4-a716-446655440001",
  "campaignName": "Customer Satisfaction Survey - Q1 2024",
  "totalResponses": 850,
  "totalMessagesSent": 1000,
  "responseRate": 85.0,
  "optionBreakdown": [
    {
      "optionIndex": 0,
      "optionText": "Very Satisfied",
      "count": 450,
      "percentage": 52.94
    },
    {
      "optionIndex": 1,
      "optionText": "Satisfied",
      "count": 280,
      "percentage": 32.94
    },
    {
      "optionIndex": 2,
      "optionText": "Neutral",
      "count": 70,
      "percentage": 8.24
    },
    {
      "optionIndex": 3,
      "optionText": "Dissatisfied",
      "count": 35,
      "percentage": 4.12
    },
    {
      "optionIndex": 4,
      "optionText": "Very Dissatisfied",
      "count": 15,
      "percentage": 1.76
    }
  ]
}

Response Fields

Field	Type	Description
campaignId	UUID	Campaign ID
campaignName	string	Campaign name
totalResponses	integer	Number of responses received
totalMessagesSent	integer	Number of surveys sent
responseRate	decimal	Response rate percentage
optionBreakdown	array	Breakdown by option
optionBreakdown[].optionIndex	integer	Option index (0-based)
optionBreakdown[].optionText	string	Option text
optionBreakdown[].count	integer	Number of responses
optionBreakdown[].percentage	decimal	Percentage of total

Example

cURL

curl -X GET "https://api.transformify.mk/api/v1/survey-results/660e8400-e29b-41d4-a716-446655440001/summary" \
  -H "X-API-Key: your-api-key"

JavaScript

const campaignId = '660e8400-e29b-41d4-a716-446655440001';

const response = await fetch(
  `https://api.transformify.mk/api/v1/survey-results/${campaignId}/summary`,
  {
    headers: { 'X-API-Key': 'your-api-key' }
  }
);

const summary = await response.json();

console.log(`Response Rate: ${summary.responseRate}%`);
console.log('Breakdown:');
summary.optionBreakdown.forEach(option => {
  console.log(`  ${option.optionText}: ${option.count} (${option.percentage}%)`);
});

Python

import requests

campaign_id = '660e8400-e29b-41d4-a716-446655440001'

response = requests.get(
    f'https://api.transformify.mk/api/v1/survey-results/{campaign_id}/summary',
    headers={'X-API-Key': 'your-api-key'}
)

summary = response.json()

print(f"Response Rate: {summary['responseRate']}%")
print('Breakdown:')
for option in summary['optionBreakdown']:
    print(f"  {option['optionText']}: {option['count']} ({option['percentage']}%)")

---

Errors

Status	Error	Description
400	Bad Request	campaignId required, or campaign is not a Survey type
401	Unauthorized	Invalid API key
404	Not Found	Campaign not found