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
429Too Many Requestsapplication/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
429Too Many Requestsapplication/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 date range you provide may cover at most 90 days. A longer range is rejected with 400 — it is no longer silently trimmed to the last 90 days, so a truncated file can never be mistaken for a complete one.

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
429Too Many Requestsapplication/json

200 Successful Response​

File Format Details:

  • The output file will be provided in either CSV or JSON format
  • The CSV file is encoded in UTF-16LE (Little Endian)
  • The CSV file starts with a UTF-16LE BOM (Byte Order Mark)
  • Fields in CSV format are tab-separated
  • Values containing special characters are enclosed in double quotes

The output file will provide 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

Rate Limiting​

The API endpoints are rate-limited to ensure fair usage and system stability. The default rate limits are:

  • Per second: 5 requests
  • Per minute: 50 requests

If you exceed these limits, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic with exponential backoff in your integration.

Error Responses​

429 Too Many Requests​

{
"detail": "Rate limit exceeded"
}