Please consult the existing API Docs for information on how to obtain an api token.
We are placing this endpoint in our “Easy Endpoints” bucket at launch - meaning the rate limits are 10 requests / second, 100 requests / minute.
This is subject to change (as is the max number of items per requests, below), so we recommend building in error handling for hitting the rate limit - please see the “Rate Limit Error Response” section.
Push Bulk CSAT Scores
Import a batch of CSAT scores into MaestroQA (max 100 items / request)
Include your api token in the request headers, under the apiToken key
Request Body (JSON)
submitted_at: string, // the iso formatted datetime the survey response was submitted [year]-[month]-[day]T[hour]:[minute]:[second]Z ex. 2017-12-13T05:00:00Z
ticket_id: string, // the id of the ticket in the helpdesk system (such as Zendesk)
agent_id: string, // the id of the agent in the helpdesk system - optional
agent_email: string, // the email of the agent in the helpdesk system - optional
score: int, // the csat score; qualtrics setups often have this as a multiple choice answer to one of the first questions in the survey
comment: string, // optional customer comment; qualtrics setups often have this as a text answer to a follow up question
score_label: string, // optional - textual equivalent to the numeric score - i.e. "Strongly Agree"
min_score: int, // recommended, but optional - the minimum score achievable - defaults to 1
max_score: int, // recommended, but optional - the maximum score achievable - defaults to 5
clarifying_answers: [ // optional - other clarifying survey answers, if your qualtrics survey contains more than the 2 typical csat questions
question: string, // the question asked
comment: string, //optional
score: int, //optional
score_label: string, // optional
min_score: int, //optional - defaults to 1
max_score: int, // optional - defaults to 5
... // 100 items / request max
All fields marked optional can be safely omitted; we do highly recommend including the min_score and max_score fields for future proofing, in case you ever change the range of values for your csat score.
Please note the ticket_id , agent_id and agent_email fields are used by MaestroQA to credit the submitted CSAT score to the correct ticket and agent; those should be the identifiers as setup in your helpdesk (such as Zendesk or Salesforce).
For Qualtrics surveys, the easiest way to get the ticket_id is to embed it as externalDataReference in the Qualtrics survey distribution.
We recommend also sending either agent_id or agent_email (if you have control over how externalDataReference is created, you could encode both ticket_id and agent_id within it and retrieve them that way); if neither agent_id or agent_email is sent, the item will not be inserted and return an error. If both are sent, agent_id will take precedence.
Status 201 CREATED
results: [ // zendesk inspired
"_id": “5840ec43ac414d9c9”, // internal maestro id
"status": "Failed: [[Error Message]]",
Status 400 ERROR
error: "[error message]",
Rate Limit Error Response
Status 429 ERROR
error: "Too many requests in the past [second/minute].",