CSAT Bulk Ingestion API Documentation
Heli Munshi avatar
Written by Heli Munshi
Updated over a week ago

Authentication

Please consult the main API Documentation for information on obtaining an api token and authenticating requests.


Rate Limit

  • 10 requests per second

  • 100 requests per 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.

Push Bulk CSAT Scores

Import a batch of CSAT scores into MaestroQA (max 100 items / request)

Request Headers

Request Body (JSON)

Note: Remove the notes following // before sending the actual API request.

Once the request is properly formatted in JSON, it should look something like this:

{
{
data: [
{
submitted_at: '2021-10-05T14:48:00.000Z', // string - the iso formatted datetime the survey response was submitted [year]-[month]-[day]T[hour]:[minute]:[second]Z ex. 2021-10-05T14:48:00.000Z - required

ticket_id: '922250816601', // string - the id of the ticket in the helpdesk system (such as Zendesk) - required

agent_id: '12345', // string - the id of the agent in the helpdesk system - either agent_id or agent_email is required

agent_email: 'bob@maestroqa.com', // string - the email of the agent in the helpdesk system - either agent_id or agent_email is required

score: 5, // integer - the primary csat score - required

comment: 'Great service!', // string - customer comment; CSAT setups often have this as a text answer to a follow up question - optional

score_label: 'Perfect', // string - textual equivalent to the numeric score - i.e. "Strongly Agree" - optional

min_score: 0, // integer - the minimum score achievable - defaults to 1 - optional

max_score: 5, // integer - the maximum score achievable - defaults to 5 - optional

clarifying_answers: [
// string - other clarifying survey answers, if your CSAT survey contains more than the 2 typical CSAT questions - optional

{
question: 'Did you like the product experience?', // string - the question asked - required

comment: 'It was OK, not as good as the support service', // string - customer comment; CSAT setups often have this as a text answer to a follow up question - optional

score_label: 'Meh', // string - textual equivalent to the numeric score - i.e. "Strongly Agree" - optional

score: 3, // integer - the question score - required

min_score: 0, // string - the minimum score achievable - defaults to 1 - optional

max_score: 5, // string - the maximum score achievable - defaults to 5 - optional
},
],
},
];
}
}

All fields marked optional can be omitted; we 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.

Success 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,

},

]

}

Did this answer your question?