Please consult the existing API Docs for information on how to obtain an api token.

Rate Limits

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)


Request Headers

Include your api token in the request headers, under the apiToken key

Request Body (JSON)


data: [


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.

Successful Response

Status 201 CREATED


status: "completed",

total: 2,

results: [ // zendesk inspired


"action": "create",

"_id": “5840ec43ac414d9c9”, // internal maestro id

"status": "Created",

"success": true,



"action": "create",

"status": "Failed: [[Error Message]]",

"success": false,




Error Response

Status 400 ERROR


error: "[error message]",


Rate Limit Error Response

Status 429 ERROR


error: "Too many requests in the past [second/minute].",


Did this answer your question?