Skip to main content

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

NameDescriptionRequiredSchema
survey_campaign_idsThe unique identifiers of the survey campaigns you want to retrieveNo[ string (uuid) ]
statusesThe status of the survey campaigns you want to retrieve. Options are: draft, active, inactive, deletedNo[ string ]
has_interaction_fromThe date from which you want to retrieve survey campaigns that have had interactionsNodate
pageThe page number of the survey campaign results you want to retrieveNointeger
per_pageThe number of survey campaign results you want to display per pageNointeger
searchA specific term or phrase you want to search for within the survey campaigns' namesNostring

Header Parameters

NameDescriptionRequiredSchema
authorizationThe authorization token to validate the request. The value should be in the format Bearer <your_api_token>Yesstring
organization-idThe unique identifier of your organizationYesstring
auth-typeThe type of authorization used for the request. In this case, the value should be tokenYesstring

Responses

CodeDescriptionContent type
200Successful Responseapplication/json
422Validation Errorapplication/json

200 Successful Response

FieldType/FormatRequiredDescription
itemsarray of objectsYesA list of survey campaigns
items.idstring (uuid)YesThe unique identifier of the survey campaign
items.namestringYesThe name of the survey campaign
items.last_interacted_atstring (date-time)NoThe most recent timestamp of when the user interacted with the survey campaign. The interaction can be: sent, sending failed, opened, answered
items.survey_questionsarray of objectsNoAn array of survey questions associated with the campaign.
items.survey_questions.idintegerYesThe unique identifier of the survey question.
items.survey_questions.typestringYesThe type of survey question. There are four question types: matrix, checkbox, multiple_choice, text
items.survey_questions.metric_typestringNoThe type of metric associated with the question. There are three metric types: nps, ces, csat
items.survey_questions.titlestringYesThe title of the survey question.
items.survey_questions.option_titles_by_iddictionaryNoKey-value pairs mapping option IDs to titles for the checkbox or multiple-choice question.
items.survey_questions.row_titles_by_iddictionaryNoKey-value pairs mapping row IDs to titles for the matrix question.
items.survey_questions.column_titlesarray of stringsNoTitles of columns for the matrix question.
totalintegerYes>= 0
pageintegerYes>= 0
per_pageintegerYes> 0
pagesintegerYes>= 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

NameDescriptionRequiredSchema
start_dateStart date for filtering survey responsesYesstring (date)
end_dateEnd date for filtering survey responsesYesstring (date)
survey_campaign_idThe unique identifier of the survey campaignYesstring (uuid)
pageThe page number of the survey response resultsNointeger (>= 0, default: 1)
per_pageThe number of survey response results per pageNointeger (0 .. 100, default: 10)

Header Parameters

NameDescriptionRequiredSchema
authorizationThe authorization token to validate the request. The value should be in the format Bearer <your_api_token>Yesstring
organization-idThe unique identifier of your organizationYesstring
auth-typeThe type of authorization used for the request. In this case, the value should be tokenYesstring

Responses

CodeDescriptionContent type
200Successful Responseapplication/json
422Validation Errorapplication/json

200 Successful Response

FieldType/FormatRequiredDescription
itemsarray of objectsYesAn array of survey response items
items.identifierstring (uuid)YesThe unique identifier of the response
items.sent_timestampstring (date-time)NoThe timestamp when the survey was sent
items.sending_failed_timestampstring (date-time)NoThe timestamp when the survey was failed to be sent
items.opened_timestampstring (date-time)NoThe timestamp when the survey was opened
items.answered_timestampstring (date-time)NoThe timestamp when the survey was answered
items.user_namestringNoThe name of the user who responded the survey
items.user_phonestringNoThe phone number of the user who responded the survey
items.user_emailstringNoThe email of the user who responded the survey
items.sourcestringNoThe 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_idstringNoThe transaction ID triggered the survey
items.metadata_mappingsdictionaryNoAdditional metadata of the survey. Key-value pairs mapping metadata variables to their values
items.answersobject (Answers)NoThe answers provided by the user
totalintegerYes>= 0
pageintegerYes>= 0
per_pageintegerYes> 0
pagesintegerYes>= 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

NameDescriptionRequiredSchema
survey_campaign_idThe unique identifiers of the survey campaign you want to retrieveYesstring (uuid)
start_dateThe lower boundary of the date range for which you want to retrieve survey responsesYesdate
end_dateThe upper boundary of the date range for which you want to retrieve survey responsesYesdate

Header Parameters

NameDescriptionRequiredSchema
authorizationThe authorization token to validate the request. The value must be in the format Bearer <your_api_token>Yesstring
organization-idThe unique identifier of your organizationYesstring
auth-typeThe type of authorization used for the request. In this case, the value must be tokenYesstring

Responses

CodeDescriptionContent type
200Successful Responsetext/csv; charset=utf-16le
422Validation Errorapplication/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 IDTimestamp sentTimestamp sending failedTimestamp openedTimestamp answeredCustomer nameCustomer phoneCustomer emailDistribution channelTransaction IDCampaign IDCampaign NameTouchpointsTagsQuestion <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