Authentication
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)
POST => https://app.maestroqa.com/api/v1/create-customer-feedback
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].", } |