Export responses API

Prerequisites

To use the APIs, you need to have a token. Tokens can be generated by an admin at the setting section in Filum CX platform. Ensure you have the necessary permissions to access the admin settings for token generation.

APIs

Access the APIs via the endpoint: https://api.filum.ai/

GET /external/survey-campaigns

Summary

Get Survey Campaigns

Query Parameters

Name	Description	Required	Schema
survey_campaign_ids	The unique identifiers of the survey campaigns you want to retrieve	No	[ string (uuid) ]
statuses	The status of the survey campaigns you want to retrieve. Options are: `draft`, `active`, `inactive`, `deleted`	No	[ string ]
has_interaction_from	The date from which you want to retrieve survey campaigns that have had interactions	No	date
page	The page number of the survey campaign results you want to retrieve	No	integer
per_page	The number of survey campaign results you want to display per page	No	integer
search	A specific term or phrase you want to search for within the survey campaigns' names	No	string

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value should be in the format `Bearer <your_api_token>`	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	The type of authorization used for the request. In this case, the value should be `token`	Yes	string

Responses

Code	Description	Content type
200	Successful Response	application/json
422	Validation Error	application/json

200 Successful Response

Field	Type/Format	Required	Description
items	array of objects	Yes	A list of survey campaigns
items.id	string (uuid)	Yes	The unique identifier of the survey campaign
items.name	string	Yes	The name of the survey campaign
items.last_interacted_at	string (date-time)	No	The most recent timestamp of when the user interacted with the survey campaign. The interaction can be: sent, sending failed, opened, answered
items.survey_questions	array of objects	No	An array of survey questions associated with the campaign.
items.survey_questions.id	integer	Yes	The unique identifier of the survey question.
items.survey_questions.type	string	Yes	The type of survey question. There are four question types: `matrix`, `checkbox`, `multiple_choice`, `text`
items.survey_questions.metric_type	string	No	The type of metric associated with the question. There are three metric types: `nps`, `ces`, `csat`
items.survey_questions.title	string	Yes	The title of the survey question.
items.survey_questions.option_titles_by_id	dictionary	No	Key-value pairs mapping option IDs to titles for the checkbox or multiple-choice question.
items.survey_questions.row_titles_by_id	dictionary	No	Key-value pairs mapping row IDs to titles for the matrix question.
items.survey_questions.column_titles	array of strings	No	Titles of columns for the matrix question.
total	integer	Yes	>= 0
page	integer	Yes	>= 0
per_page	integer	Yes	> 0
pages	integer	Yes	>= 0

Response samples

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "last_interacted_at": "2019-08-24T14:15:22Z",
      "survey_questions": [
        {
          "id": 0,
          "type": "string",
          "metric_type": "string",
          "title": "string",
          "option_titles_by_id": {
            "option_id_1": "option_title_1",
            "option_id_2": "option_title_2"
          },
          "row_titles_by_id": {
            "row_id_1": "row_title_1",
            "row_id_2": "row_title_2"
          },
          "column_titles": [
            "string"
          ]
        }
      ]
    }
  ],
  "total": 0,
  "page": 0,
  "per_page": 0,
  "pages": 0
}

GET /external/survey-responses

Summary

Get Survey Campaign Responses

Query Parameters

Name	Description	Required	Schema
start_date	Start date for filtering survey responses	Yes	string (date)
end_date	End date for filtering survey responses	Yes	string (date)
survey_campaign_id	The unique identifier of the survey campaign	Yes	string (uuid)
page	The page number of the survey response results	No	integer (>= 0, default: 1)
per_page	The number of survey response results per page	No	integer (0 .. 100, default: 10)

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value should be in the format `Bearer <your_api_token>`	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	The type of authorization used for the request. In this case, the value should be `token`	Yes	string

Responses

Code	Description	Content type
200	Successful Response	application/json
422	Validation Error	application/json

200 Successful Response

Field	Type/Format	Required	Description
items	array of objects	Yes	An array of survey response items
items.identifier	string (uuid)	Yes	The unique identifier of the response
items.sent_timestamp	string (date-time)	No	The timestamp when the survey was sent
items.sending_failed_timestamp	string (date-time)	No	The timestamp when the survey was failed to be sent
items.opened_timestamp	string (date-time)	No	The timestamp when the survey was opened
items.answered_timestamp	string (date-time)	No	The timestamp when the survey was answered
items.user_name	string	No	The name of the user who responded the survey
items.user_phone	string	No	The phone number of the user who responded the survey
items.user_email	string	No	The email of the user who responded the survey
items.source	string	No	The channel through which the survey was distributed (e.g., web, email). There are six channels: `Anonymous Link`, `POS`, `Website`, `Zalo`, `Email`, and `Mobile`.
items.transaction_id	string	No	The transaction ID triggered the survey
items.metadata_mappings	dictionary	No	Additional metadata of the survey. Key-value pairs mapping metadata variables to their values
items.answers	object (Answers)	No	The answers provided by the user
total	integer	Yes	>= 0
page	integer	Yes	>= 0
per_page	integer	Yes	> 0
pages	integer	Yes	>= 0

Response samples

{
  "id": null,
  "name": "string",
  "items": [
    {
      "identifier": "14d3030c-3b61-4070-b902-342f80e99364",
      "sent_timestamp": "2019-08-24T14:15:22Z",
      "sending_failed_timestamp": "2019-08-24T14:15:22Z",
      "opened_timestamp": "2019-08-24T14:15:22Z",
      "answered_timestamp": "2019-08-24T14:15:22Z",
      "user_name": "string",
      "user_phone": "string",
      "user_email": "string",
      "source": "string",
      "transaction_id": "string",
      "metadata_mappings": {},
      "answers": {}
    }
  ],
  "total": 0,
  "page": 0,
  "per_page": 0,
  "pages": 0
}

POST /external/survey-responses/export

Summary

Export Survey Responses From A Survey Campaign

Limitations:

Each export request can include up to 5000 rows of data.
The data exported must fall within a date range that does not exceed 30 days. If the date range you provide is more than 30 days, the system will automatically adjust the start date. It will do this by counting back 30 days from the end date you provided. This new date will then be used as the start date for the data export.

Query Parameters

Name	Description	Required	Schema
survey_campaign_id	The unique identifiers of the survey campaign you want to retrieve	Yes	string (uuid)
start_date	The lower boundary of the date range for which you want to retrieve survey responses	Yes	date
end_date	The upper boundary of the date range for which you want to retrieve survey responses	Yes	date

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value must be in the format `Bearer <your_api_token>`	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	The type of authorization used for the request. In this case, the value must be `token`	Yes	string

Responses

Code	Description	Content type
200	Successful Response	text/csv; charset=utf-16le
422	Validation Error	application/json

200 Successful Response

The output file will be provided in TSV (Tab-separated values) format with the following information:

Unique identifier
Time information (in UTC +7 timezone)
Customer information
Distribution channel information
Transaction ID
Campaign information
Touchpoints information
Survey response tags
Survey questions and answers information
Additional metadata information

Sample columns are:

Response ID	Timestamp sent	Timestamp sending failed	Timestamp opened	Timestamp answered	Customer name	Customer phone	Customer email	Distribution channel	Transaction ID	Campaign ID	Campaign Name	Touchpoints	Tags	Question <question_id>: <question_title>	Question <question_id> - <row_id>: <question_title> - <row_title>	Question <question_id> - <option_id>: <question_title> - <option_text>	<metadata_variable>

Each row in the table will represent a unique identifier of a response. The columns will contain the following information:

Response ID: A unique identifier.
Timestamp sent: The time the survey was sent.
Timestamp sending failed: The time the survey failed to send.
Timestamp opened: The time the survey was opened.
Timestamp answered: The time the survey was answered.
Customer name: The name of the customer.
Customer phone: The phone number of the customer.
Customer email: The email of the customer.
Distribution channel: The channel through which the survey was distributed.
Transaction ID: The unique identifier of the transaction associated with the survey.
Campaign ID: The unique identifier of the survey campaign.
Campaign Name: The name of the survey campaign.
Touchpoints: A list of touchpoints associated with the survey campaign.
Tags: A list of tags associated with the survey response.
Survey questions and answers columns:
- For text, multiple-choice, and checkbox questions:
  - Column name format: Question <question_id>: <question_title>
  - Column value:
    - Customer input for text questions
    - Customer selection for multiple-choice questions
    - Customer selections separated by | for checkbox questions
- For matrix questions:
  - Column name format: Question <question_id> - <row_id>: <question_title> - <row_title>
  - Column value: Customer selection
- For ranking questions:
  - Column name format: Question <question_id> - <option_id>: <question_title> - <option_title>
  - Column value: Customer selected ranking. The ranking value starts from 1
Additional metadata columns: Each metadata will have a separate column with:
- Column name: metadata variable
- Column value: metadata value

Prerequisites​

APIs​

GET /external/survey-campaigns​

Summary​

Query Parameters​

Header Parameters​

Responses​

200 Successful Response​

GET /external/survey-responses​

Summary​

Query Parameters​

Header Parameters​

Responses​

200 Successful Response​

POST /external/survey-responses/export​

Summary​

Query Parameters​

Header Parameters​

Responses​

200 Successful Response​

Prerequisites

APIs

GET /external/survey-campaigns

Summary

Query Parameters

Header Parameters

Responses

200 Successful Response

GET /external/survey-responses

Summary

Query Parameters

Header Parameters

Responses

200 Successful Response

POST /external/survey-responses/export

Summary

Query Parameters

Header Parameters

Responses

200 Successful Response