Survey API Documentation

Overview

This document describes the Survey API endpoints, request/response schemas, validation rules, error handling, and usage examples.

Endpoints

Create Survey

Method: POST
Path: /v2/survey/create
Headers: X-API-Key (required)
Request Body: CreateSurveyRequest
Response: SurveyResponse
Description: Create a new survey.

Delete Survey

Method: DELETE
Path: /v2/survey/delete
Headers: X-API-Key (required)
Request Body: DeleteSurveyRequest
Response: SurveyResponse
Description: Delete a survey by ID.

Get All Surveys

Method: GET
Path: /v2/survey/getAll
Headers: X-API-Key (required)
Query Params: resultSize (optional), pageToken (optional)
Response: JSON object (list of surveys)
Description: Get all surveys, optionally limited by result size and paginated.

Get Survey Messages

Method: GET
Path: /v2/survey/getSurvMsgs
Headers: X-API-Key (required)
Query Params: surveyID (required), resultSize (optional), pageToken (optional)
Response: JSON object (list of messages)
Description: Get messages for a specific survey.

Resend Survey Message

Method: POST
Path: /v2/survey/resendMsg
Headers: X-API-Key (required)
Request Body: ResendSurveyMessageRequest
Response: JSON object
Description: Resend a failed survey message by messageKey and flowKey.

Update Survey

Method: PUT
Path: /v2/survey/update
Headers: X-API-Key (required)
Request Body: UpdateSurveyRequest
Response: SurveyResponse
Description: Update a survey's name, send time, or flowKey.

Request & Response Schemas

CreateSurveyRequest

type CreateSurveyRequest struct {
  Name      string
  Message   string
  Clients   []SurveyClient
  JSON      string
  TempMsgID string
  FlowKey   string
}

DeleteSurveyRequest

type DeleteSurveyRequest struct {
  ID int
}

UpdateSurveyRequest

type UpdateSurveyRequest struct {
  ID      int
  Name    string
  SendAt  string
  FlowKey string
}

ResendSurveyMessageRequest

type ResendSurveyMessageRequest struct {
  MessageKey string
  FlowKey    string
}

SurveyResponse

type SurveyResponse struct {
  ID        int
  Name      string
  Message   string
  Clients   []SurveyClient
  JSON      string
  TempMsgID string
  FlowKey   string
  Status    string
  CreatedAt string
  UpdatedAt string
}

SurveyClient

type SurveyClient struct {
  AccountID string
  Params    []string
}

Validation & Business Rules

Rule Description	Applies To	Error Message
`flowKey` required	Create Survey	"flowKey required"
At least 2 clients required	Create Survey	"invalid request: at least 2 clients required"
TempMsgID must exist if provided	Create Survey	"invalid request: template not found"
JSON or TempMsgID required	Create Survey	"invalid request: JSON or TempMsgID required"
If TempMsgID is present and Message is empty, BODY text is auto-filled from template	Create Survey	(auto-filled, no error)
Params count must match variables in JSON (first client)	Create Survey	"invalid request: not enough params for variables in Template"
Each client's params count must match number of variables in template	Create Survey	"invalid request: each client must have params for all template variables"

All endpoints require X-API-Key header.

Error Handling

400 Bad Request: Invalid request body, missing required fields, or validation errors.
502 Bad Gateway: Upstream service call failed.
500 Internal Server Error: Server-side error or marshalling failure.

Examples

Create Survey Request Examples

1. Only TempMsgID and flowKey

{
  "name": "Customer Feedback Survey",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["John", "ORD-12345"]
    }
  ],
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "flowKey": "flow-12345",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: The template with this TempMsgID will be used. If the template has a BODY, its text will be auto-filled as the survey message. JSON will be auto-filled from the template. flowKey is required.

2. TempMsgID, JSON, and flowKey

{
  "name": "Customer Feedback Survey",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["John", "ORD-12345"]
    }
  ],
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "JSON": "{ \"to\": \"<accountID>\", \"type\": \"template\", \"template\": { \"namespace\": \"<namespace>\", \"language\": { \"policy\": \"deterministic\", \"code\": \"en_US\" }, \"name\": \"survey_feedback\", \"components\": [] } }",
  "flowKey": "flow-12345",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: The template with this TempMsgID will be used, but the provided JSON will override the template's JSON. flowKey is required.

3. TempMsgID, JSON, Message, and flowKey

{
  "name": "Customer Feedback Survey",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["John", "ORD-12345"]
    }
  ],
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "JSON": "{ \"to\": \"<accountID>\", \"type\": \"template\", \"template\": { \"namespace\": \"<namespace>\", \"language\": { \"policy\": \"deterministic\", \"code\": \"en_US\" }, \"name\": \"survey_feedback\", \"components\": [] } }",
  "message": "We value your feedback! Please answer the following questions.",
  "flowKey": "flow-12345",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: The template with this TempMsgID will be used, the provided JSON will override the template's JSON, and the provided message will override the template's BODY text. flowKey is required.

4. All Fields (Typical Example)

{
  "name": "Welcome Survey",
  "message": "Welcome to our service! Please take a moment to complete this survey.",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["https://example.com/image1.png", ""]
    }
  ],
  "JSON": "{ \"to\": \"<accountID>\", \"type\": \"template\", ... }",
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "flowKey": "flow-12345",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: All fields are explicitly set. The provided values will be used directly. flowKey is required.

Note:
name is required and indicates the survey name.
flowKey is required for all create.
SendAt is optional and can be used to schedule the survey (ISO 8601 format, e.g. "2025-03-03T14:32:25+03:00").

Delete Survey Request

{
  "id": 385
}

Update Survey Request

{
  "id": 387,
  "name": "Updated Survey Name",
  "SendAt": "2025-03-04T11:31:25.000Z",
  "flowKey": "flow-67890"
}

Resend Survey Message Request

{
  "messageKey": "C030200170205C476A3B882B2702FF",
  "flowKey": "flow-12345"
}

Documentation