Overview

The MaestroQA API allows users to access and interact with their quality assurance data programmatically. By using the API, users can automate repetitive tasks, integrate MaestroQA with other tools, and build custom applications that leverage their QA data. In this article, we'll explore the main features of the MaestroQA API, show examples of how it can be used, and provide guidance on how to get started.

Whether you're a seasoned developer or new to APIs, this article will help you understand how to unlock the full potential of MaestroQA by using its API.

Authentication & API Tokens

Rate Limits

Troubleshooting

Endpoints

Exports
- Raw Grading Export (grading data)
- Retrieve Export Results
- Agent Groups Export
- Audit Logs Export (activity log data)
Tickets
Agents
- Create an Agent
- Update an Agent
  - Add new agent ID
  - Update agent availability
Coaching Points
- Get a Coaching Point
- List Coaching Points
To-Dos
- Get a To-Do
- List To-Dos
Coaching Sessions
- Get a Coaching Session
- List Coaching Sessions
SCIM API

Authentication

In order to make requests to the Maestro QA API, you must attach a valid API token to your request.

Obtaining an API Token

API tokens can be generated in the MaestroQA dashboard on the Other Settings page. Within "Other Settings", scroll down to the API Tokens section and click "Create New Token".

By default, API Tokens expire every 90 days for security purposes. This expiration can be turned off, or tokens can be deactivated manually.

Authenticating Requests

An API token must be provided for all requests. The token should be passed in the request's headers, in the format:

'apitoken': 'YOUR_API_TOKEN'

Example (Python)

import requests

headers = {
  'Content-Type': 'application/json',
  'apitoken': 'YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)

Certain endpoints allow tokens to be passed in the request body (noted in the endpoint's documentation); this is supported for backward compatibility only and is subject to change.

__________________________________________________________________

Formats

1. All dates should be UTC offset datetime strings, formatted according to the extended ISO 8601 format (reference)

[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z

ex. 2017-12-13T05:00:00Z

2. Each endpoint’s request parameters and response content should be JSON-encoded

Endpoints

The * symbol is used to denote required parameters

If a parameter is optional, it may be omitted from the request parameters. If an optional parameter is included, it must contain a valid value.

Request A “Raw” Export

Raw exports are the equivalent to the Raw CSV export in the MaestroQA dashboard. The export will include grades that were last updated between the specified start date and end date.

Raw exports generate a zip file containing a CSV for each level of rubric scores:

total rubric scores
section scores
individual answer scores
annotations
CSAT

Definition

POST https://app.maestroqa.com/api/v1/request-raw-export

Body Parameters

Name	Type	Description
startDate*	string (see formats)	Include grades that were updated after this date (required)
endDate*	string (see formats)	Include grades that were updated before this date (required)
name	string	Name for the export. Defaults to a randomly generated name (optional)
singleFileExport	enum (individual_answers, section_scores, total_scores, annotations, csat)	Specify a single `csv` file to export instead of the default zip file with all `csvs` (optional)
includeCalibrations	enum (all, none, only)	Specify whether calibration scores should be included in the export. "none": (default) - don't include calibration scores "only": only include calibration scores "all": include all scores, regardless of type (optional)
includeGraderQA	boolean	Specify whether grader QA benchmark scores should be included in the export. Default is `false` (optional)
includeDeleted	boolean	Specify whether deleted answers should be included in the export. Default is false (optional)
apiToken	string	See authentication (optional) - token may be passed in request body or in request headers

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Name	Type	Description
exportId	string	ID of the export that was requested

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-raw-export'

payload = {
    'startDate': '2018-08-13T00:00:00Z',
    'endDate': '2018-08-19T00:00:00Z',
    'name': 'Weekly Maestro Grades Export'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Retrieve the results of an export

After an export has been requested, check its status and fetch the URL from which to download the export’s results.

Definition

GET https://app.maestroqa.com/api/v1/get-export-data

Body Parameters

Name	Type	Description
exportId*	string	The ID of the export whose results should be returned (required)
apiToken	string	See authentication (optional) - token may be passed in request body or in request headers

Response

Status and result data for the requested export

Name	Type	Description
status	enum (requested, in_progress, complete, errored)	The status of the export
dataUrl	string	If status is "complete" and there is data to download, contains the URL to download the export. Otherwise, contains an empty string.

Note: if there was no matching data for the parameters requested (ex. if you request dates in the future), the dataUrl field will be empty, even when the status is 'complete' as there is nothing to download.

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/get-export-data'

payload = {
    'exportId': 'THE_EXPORT_ID'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, json=payload, headers=headers)

Example Response

{
    'status': 'complete',
    'dataUrl': 'https://subdomain.s3.amazonaws.com/path/to/file'
}

Here is a Data Dictionary for the files contained within the resulting export.

__________________________________________________________________

Request an “agent groups” export

An “agent groups” export is the equivalent to the Agent Groups export in the MaestroQA App. This will export all the agent groups and group membership.

Definition

POST https://app.maestroqa.com/api/v1/request-groups-export

Body Parameters

Name	Type	Description
name	string	Name for the export. Defaults to a randomly generated name (optional)
includeUnavailable	boolean	Whether to include all agents, or just those currently marked “available”. Default is `false`. (optional)
apiToken	string	See authentication (optional) - token may be passed in request body or in request headers

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Name	Type	Description
exportId	string	ID of the export that was requested

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-groups-export'

payload = {
    'name': 'Maestro Agent Groups Export',
    'includeUnavailable': False
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Request an “audit logs” export

An “audit log” export is the equivalent to the Activity Logs export in the MaestroQA App. This will export all the user activity in your account during the specified date range. See "What Can I Track in the Activity Log" for details on what is tracked in the activity log.

Definition

POST https://app.maestroqa.com/api/v1/request-audit-log-export

Body Parameters

Name	Type	Description
startDate*	string (see formats)	Include logs that were created after this date (required)
endDate*	string (see formats)	Include logs that were created before this date (required)
name	string	Name for the export. Defaults to a randomly generated name (optional)
apiToken	string	See authentication (optional) - token may be passed in request body or in request headers

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Name	Type	Description
exportId	string	ID of the export that was requested

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-audit-log-export'

payload = {
    'startDate': '2018-08-13T00:00:00Z',
    'endDate': '2018-08-19T00:00:00Z',
    'name': 'Maestro Activity Log Export',
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Create a Ticket

Create a new Ticket in your MaestroQA account.

Definition

POST https://app.maestroqa.com/api/v1/tickets

Body Parameters

Name	Type	Description
ticket_id*	string	A unique identifier for the ticket. (required) Note: this id must be unique - if the id is in use by any other ticket in your account, the request will fail with a 409 Conflict error
type*	string	The ticket type/source from your external support system (required)
subject*	string	The ticket's subject (required)
agents*	array[string]	A list of the IDs of agents associated with the ticket (required) See Guide to User Roles for information about Agent IDs
link*	string	A link to the ticket in your external resource (required)
body*	string	The text content of the ticket (required)
tags	string	The ticket's tags, formatted as a comma-separated string
status	string	The ticket's status (ex: "Closed")
csat_score	number	The CSAT score for the ticket
first_seen	date string (see formats)	The date the ticket was created Defaults to the current date
last_seen	date string (see formats)	The date of the last activity on the ticket Defaults to the current date
attributes	object	Custom attributes for the ticket Note: these attributes must already exist in your MaestroQA account. The values passed for each key will be validated against the attribute's expected value type (ex: string, boolean, etc.). Unrecognized attributes will be ignored.

Response

The ticket that was created

Name	Type	Description
ticket_id	string	A unique identifier for the ticket.
type	string	The ticket type/source from your external support system
subject	string	The ticket's subject
agents	array[string]	A list of the IDs of agents associated with the ticket
link	string	A link to the ticket in your external resource
body	string	The text content of the ticket
tags	string	The ticket's tags, formatted as a comma-separated string
status	string	The ticket's status
csat_score	number	The CSAT score for the ticket
first_seen	date string (see formats)	The date the ticket was created
last_seen	date string (see formats)	The date of the last activity on the ticket
attributes	object	The ticket's custom attributes

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/tickets'

payload = {
    'ticket_id': 'unique_ticket_id',
    'type': 'custom helpdesk',
    'subject': 'New ticket',
    'link': 'http://www.mynewticket.com',
    'body': 'The text content of this ticket',
    'status': 'open',
    'agents': ['this_agent_id'],
    'tags': 'login,support,escalated',
    'csat_score': 5,
    'first_seen': '2022-02-02T00:00:00.000Z',
    'last_seen': '2022-03-07T00:00:00.000Z',
    'attributes': {
      'public_comment_count': 5,
      'group': 'Support',
      'first_resolution_time_total_minutes': 1023
    }
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{
  '_id': 'unique_maestro_id_for_ticket',
  'ticket_id': 'unique_ticket_id',
  'type': 'custom helpdesk',
  'subject': 'New ticket',
  'link': 'http://www.mynewticket.com',
  'body': 'The text content of this ticket',
  'status': 'open',
  'agents': ['this_agent_id'],
  'tags': 'login,support,escalated',
  'csat_score': 5,
  'first_seen': '2022-02-02T00:00:00.000Z',
  'last_seen': '2022-03-07T00:00:00.000Z',
  'attributes': {
    'public_comment_count': 5,
    'group': 'Support',
    'first_resolution_time_total_minutes': 1023
  }
}

__________________________________________________________________

Update a Ticket

Update an existing Ticket in your MaestroQA account.

Note: tickets synced from helpdesk integrations cannot be manually updated

Definition

PATCH https://app.maestroqa.com/api/v1/tickets/:ticket_id

Path Parameters

Name	Type	Description
ticket_id*	string	The unique identifier for the ticket (required)

Body Parameters

Name	Type	Description
type	string	The ticket type/source from your external support system
subject	string	The ticket's subject
agents	array[string]	A list of the IDs of agents associated with the ticket See Guide to User Roles for information about Agent IDs
link	string	A link to the ticket in your external resource
body	string	The text content of the ticket
tags	string	The ticket's tags, formatted as a comma-separated string
status	string	The ticket's status (ex: "Closed")
csat_score	number	The CSAT score for the ticket
first_seen	date string (see formats)	The date the ticket was created
last_seen	date string (see formats)	The date of the last activity on the ticket
attributes	object	Custom attributes for the ticket Note: these attributes must already exist in your MaestroQA account. The values passed for each key will be validated against the attribute's expected value type (ex: string, boolean, etc.). Unrecognized attributes will be ignored.

Response

The updated ticket

Name	Type	Description
ticket_id	string	A unique identifier for the ticket.
type	string	The ticket type/source from your external support system
subject	string	The ticket's subject
agents	array[string]	A list of the IDs of agents associated with the ticket
link	string	A link to the ticket in your external resource
body	string	The text content of the ticket
tags	string	The ticket's tags, formatted as a comma-separated string
status	string	The ticket's status
csat_score	number	The CSAT score for the ticket
first_seen	date string (see formats)	The date the ticket was created
last_seen	date string (see formats)	The date of the last activity on the ticket
attributes	object	The ticket's custom attributes

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/tickets/unique_ticket_id'

payload = {
    'subject': 'Updated subject!',
    'status': 'closed',
    'last_seen': '2022-03-15T00:00:00.000Z'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.patch(url, json=payload, headers=headers)

Example Response

{
  '_id': 'unique_maestro_id_for_ticket',
  'ticket_id': 'unique_ticket_id',
  'type': 'custom helpdesk',
  'subject': 'Updated subject!',
  'link': 'http://www.mynewticket.com',
  'body': 'The text content of this ticket',
  'status': 'closed',
  'agents': ['this_agent_id'],
  'tags': 'login,support,escalated',
  'csat_score': 5,
  'first_seen': '2022-02-02T00:00:00.000Z',
  'last_seen': '2022-03-15T00:00:00.000Z'
}

__________________________________________________________________

Delete a Ticket

Delete an existing Ticket in your MaestroQA account.

Note: tickets synced from helpdesk integrations cannot be manually deleted

Definition

DELETE https://app.maestroqa.com/api/v1/tickets/:ticket_id

Path Parameters

Name	Type	Description
ticket_id*	string	The unique identifier for the ticket (required)

Response

N/A - successful delete requests will receive a 200 OK response

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/tickets/unique_ticket_id'

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.delete(url, headers=headers)

Create a Ticket Comment

Create a comment for a specific ticket. Comments can represent dialogue from customers or agents.

Definition

POST https://app.maestroqa.com/api/v1/comments

Body Parameters

Name	Type	Required	Description
body	string	Yes	The content of the comment
ticket_id	string	Yes	The unique identifier of the ticket to which the comment is being added
author_id	string	No	The identifier of the author (agent or customer) of the comment
role	enum (customer, agent)	No	The role of the comment author (agent or customer)
channel	string	No	The communication channel through which the comment was made (e.g. chat)
public	boolean	No	Whether or not the comment was public. Defaults to true.
time	date string (see formats)	No	The timestamp of when the comment was made. Defaults to the current time

Response

The comment that was created

Name	Type	Description
_id	string	The unique identifier for the comment
body	string	The content of the comment
ticket_id	string	The identifier of the ticket associated with the comment
author_id	string	The identifier of the author
role	enum (agent, customer)	The role of the comment author
channel	string	The channel used for the comment
public	boolean	Whether the comment is public
time	date string	The timestamp of the comment

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/comments'

payload = {
    'ticket_id': '427406478143',
    'channel': 'chat',
    'time': '2023-11-03T16:38:53.508Z',
    'body': 'Hi, can I get some help?',
    'role': 'customer',
    'author_id': 'customer_12345',
    'public': True
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{
  "body": "Hi, can I get some help?",
  "author_id": "customer_12345",
  "role": "customer",
  "channel": "chat",
  "public": true,
  "time": "2023-11-03T16:38:53.508Z",
  "ticket_id": "427406478143",
  "_id": "16906fb5ce9d57646fa38362_427406478143_W7OU22JH4Q"
}

Create an Attachment

Create an attachment for a specific ticket. This enabled attaching photos, audio, files, and video to tickets complementing the existing ticket and comment creation APIs.

The attachment flow is posting a URL that is accessible to MaestroQA, then MaestroQA asynchronously downloads the attachment and formats an attachment to a ticket. This process can take a few hours so do not expect attachments to be immediately available for use within the application. MaestroQA uses static IPs available upon request to enable IP Whitelisting.

Definition

POST https://app.maestroqa.com/api/v1/attachments

Body Parameters

Name	Type	Required	Description
url	string	Yes	URL of the attachment to attach. See Summary for notes about url accessibility.
ticket_id	string	Yes	The unique identifier of the ticket to which the comment is being added
content_type	string	Yes	The mime type of the file being sent - ex. audio/mp3
id	string	No	Unique id of the attachment - helpful for identifying the attachment, for reference, or potentially stitching. If none is provided, a random ID will be generated and returned in the response.
author_id	string	No	ID of the author to associate the attachment to a particular agent (or the customer). This can be particularly helpful when there are multiple agents on a ticket or you want to differentiate agent vs customer comments.
public	boolean	No	If this attachment should create a public or private attachment comment, defaults to true.
timestamp	date string (see formats)	No	The timestamp the attachment comment should show. This is helpful to ensure comments and attachments show in the proper chronological order. If empty will default to current time.

Response

The comment that was created

Name	Type	Description
id	string	The unique identifier for the attachment

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/attachments'

payload = {
    'ticketId': '1234',
    'url': 'https://etherrock.com/0.png',
    'public': true,
    'timestamp': '2020-12-13T05:00:00Z'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{
  "id": "16906fb5ce9d57646fa38362_427406478143_W7OU22JH4Q"
}

Create an Agent

Definition

POST https://app.maestroqa.com/api/v1/agents

Body Parameters

Name	Type	Required	Description
name	string	Yes	The full name of the agent
available	boolean	Yes	Agent's availability status
email	string	Yes	The email address of the agent *must be unique (see error responses)
agentGroupId	string	No	The identifier for the agent group the agent should be added to
agentId	string	No	A unique alphanumeric identifier for the agent. If not provided, a random id is generated *must be unique if provided (see error responses)

Success Response

The agent that was created

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/agents'

payload = {
  'name': 'Allison Agent',
  'available': True,
  'email': 'brand_new_agent@maestroqa.com',
  'agentId': 'allisonagent',
  'agentGroupId': 'ZBceBjFgQjNY2qLof'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{
    "_id": "js6LYgg4Ey3EqYhfi",
    "name": "Allison Agent",
    "agentId": "allisonagent",
    "available": true,
    "email": "brand_new_agent@maestroqa.com",
    "agentGroupId": "ZBceBjFgQjNY2qLof"
}

Update an Agent (add agent id to agent)

Definition

POST https://app.maestroqa.com/api/v1/add-id-to-agent

Body Parameters

Name	Type	Required	Description
email	string	Yes	The email address of the agent *must be unique (see error responses)
agentId	string	Yes	A unique alphanumeric identifier for the agent. *must be unique if provided (see error responses)

Success Response

The agent that was updated

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/add-id-to-agent'

payload = {
  'email': 'brand_new_agent@maestroqa.com',
  'agentId': 'allisonagent'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Update an Agent (update agent availability)

Definition

POST https://app.maestroqa.com/api/v1/update-agent-availability

Body Parameters

Name	Type	Required	Description
email	string	Yes	The email address of the agent *must be unique (see error responses)
available	boolean	Yes	The value to update agent availability to

Success Response

The agent that was updated

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/update-agent-availability'

payload = {
  'email': 'brand_new_agent@maestroqa.com',
  'available': True
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Retrieve a Single To-do

Fetch a single todo item by ID

Definition

GET https://app.maestroqa.com/api/v1/todos/:id

Path Parameters

Name	Type	Description
id	string	The unique identifier of the todo to retrieve

Response

The todo item

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/todos/CGsTFnNi5P8riTHmC'

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, headers=headers)

Example Response

{
  "id": "CGsTFnNi5P8riTHmC",
  "title": "A Todo",
  "createdAt": "2023-06-28T16:03:21.089Z",
  "updatedAt": "2023-06-28T16:03:30.804Z",
  "agentId": "72999",
  "creatorId": "HkeYnymy3fhgf3j5F",
  "status": "incomplete",
  "type": "general",
  "coachingSessionIds": [],
  "description": "This todo's description text"
}

Retrieve To-dos

Fetch multiple todos based on filter criteria.

Definition

GET https://app.maestroqa.com/api/v1/todos

Query Parameters

Name	Type	Description
agentId	string	Filter to only todos for the provided agent ID
creatorId	string	Filter to only todos created by the provided user ID
startDate	date string (see formats)	Filter to only todos created after the provided date
endDate	date string (see formats)	Filter to only todos created before the provided date
count	integer	The number of results to return
startIndex	integer	Offset to start pagination search results

Response

Name	Type	Description
startIndex	integer	Offset of paginated search results
totalResults	integer	Total number of todos that match the provided query filters
itemsPerPage	integer	The number of results per page
Resources	array[todos]	List of todos matching the filter criteria

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/todos'
params = {
    'count': 1,
    'startIndex': 50,
    'startDate': '2023-06-01T15:08:45.781Z',
    'endDate': '2023-08-01T15:08:45.781Z',
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, params=params, headers=headers)

Example Response

{
  "startIndex": 50,
  "totalResults": 254,
  "itemsPerPage": 1,
  "Resources": [
 {
    "id": "P9MTc9MogtHZpDKqm",
    "title": "2. My First App",
    "createdAt": "2023-06-26T21:01:32.469Z",
    "updatedAt": "2023-06-26T21:01:32.469Z",
    "agentId": "5595649818",
    "creatorId": "zme7PkariKd5Hb4fT",
    "status": "incomplete",
    "type": "guru",
    "answerId":     "16906fb5ce9d57646fa38362_5311138_QqJEN5t8LXZRQZd4a_5595649818_GRADER_grading",
    "description": ""
  }
 ]
}

Retrieve a Single Coaching Point

Fetch a single coaching point by ID

Definition

GET https://app.maestroqa.com/api/v1/coaching-points/:id

Path Parameters

Name	Type	Description
id	string	The unique identifier of the coaching point to retrieve

Response

The coaching point

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/coaching-points/HHk4xnKwwpYsJHTnq'

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, headers=headers)

Example Response

{
  "id": "6Lt3yHNcBBEyMSK8n",
  "createdAt": "2023-06-21T17:52:36.687Z",
  "updatedAt": "2023-06-24T05:42:18.599Z",
  "agentId": "72999",
  "creatorId": "zme7PkariKd5Hb4fT",
  "criteriaId": null,
  "rubricId": "AatxWWtXWKcfiN34E",
  "answerId": "16906fb5ce9d57646fa38362_5310985_AatxWWtXWKcfiN34E_542897_GRADER_grading",
  "type": "opportunities",
  "classification": "qa",
  "coachNotes": "Let's talk about greeting ",
  "coachingSessionIds": [],
  "textContent": ""
}

Retrieve Coaching Points

Fetch multiple coaching points based on filter criteria.

Definition

GET https://app.maestroqa.com/api/v1/coaching-points

Query Parameters

Name	Type	Description
agentId	string	Filter to only coaching points for the provided agent ID
creatorId	string	Filter to only coaching points created by the provided user ID
startDate	date string (see formats)	Filter to only coaching points created after the provided date
endDate	date string (see formats)	Filter to only coaching points created before the provided date
count	integer	The number of results to return
startIndex	integer	Offset to start pagination search results

Response

Name	Type	Description
startIndex	integer	Offset of paginated search results
totalResults	integer	Total number of coaching points that match the provided query filters
itemsPerPage	integer	The number of results per page
Resources	array[coaching points]	List of coaching points matching the filter criteria

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/coaching-points'
params = {
    'count': 3,
    'agentId': '72999',
    'startDate': '2023-06-01T15:08:45.781Z',
    'endDate': '2023-08-01T15:08:45.781Z',
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, params=params, headers=headers)

Example Response

{
    "startIndex": 0,
    "totalResults": 16,
    "itemsPerPage": 3,
    "Resources": [
        {
            "id": "6Lt3yHNcBBEyMSK8n",
            "createdAt": "2023-06-21T17:52:36.687Z",
            "updatedAt": "2023-06-24T05:42:18.599Z",
            "agentId": "72999",
            "creatorId": "zme7PkariKd5Hb4fT",
            "criteriaId": null,
            "rubricId": "AatxWWtXWKcfiN34E",
            "answerId": "16906fb5ce9d57646fa38362_5310985_AatxWWtXWKcfiN34E_542897_GRADER_grading",
            "type": "opportunities",
            "classification": "qa",
            "coachNotes": "Let's talk about greeting",
            "coachingSessionIds": [],
            "textContent": ""
        },
        {
            "id": "Ai37xkEiq2HPy8zXs",
            "createdAt": "2023-07-10T18:10:09.340Z",
            "updatedAt": "2023-07-10T18:10:09.340Z",
            "agentId": "72999",
            "creatorId": "zme7PkariKd5Hb4fT",
            "type": "strengths",
            "classification": "general",
            "coachNotes": "Good job asking probing questions ",
            "coachingSessionIds": [
                "2TGWZ8YdWnK9HyPgm"
            ],
            "textContent": ""
        },
        {
            "id": "B8wj8BptAFzgjWdti",
            "createdAt": "2023-06-23T19:00:00.861Z",
            "updatedAt": "2023-06-24T05:42:18.599Z",
            "agentId": "72999",
            "creatorId": "nQHdkaE76F7upgJwr",
            "type": "n/a",
            "classification": "general",
            "coachNotes": null,
            "coachingSessionIds": [],
            "textContent": ""
        }
    ]
}

Retrieve a Single Coaching Session

Fetch a single coaching session by ID

Definition

GET https://app.maestroqa.com/api/v1/coaching-sessions/:id

Path Parameters

Name	Type	Description
id	string	The unique identifier of the coaching session to retrieve

Response

The coaching session

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/coaching-sessions/25oWGcmSd34yZRR84'

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, headers=headers)

Example Response

{
  "id": "25oWGcmSd34yZRR84",
  "name": "Sample Coaching Session",
  "createdAt": "2023-07-13T16:02:42.255Z",
  "updatedAt": "2023-07-13T16:02:53.622Z",
  "agentId": "72999",
  "agentName": "Harrison Charles",
  "coachId": "zme7PkariKd5Hb4fT",
  "coachName": "Charlie Smith",
  "creatorId": "zme7PkariKd5Hb4fT",
  "agentNotes": "Agent's notes",
  "coachNotes": "Coach's notes",
  "coachPrivateNotes": "Private (not shared with agent) notes",
  "sessionContents": "Contents of the sessions's 'Overview' tab",
  "coachingTemplateId": "16906fb5ce9d57646fa38362",
  "meetingFormat": "inPerson",
  "agentConfirmed": false,
  "coachConfirmed": false
}

Retrieve Coaching Sessions

Fetch multiple coaching sessions based on filter criteria.

Definition

GET https://app.maestroqa.com/api/v1/coaching-sessions

Query Parameters

Name	Type	Description
agentId	string	Filter to only coaching sessions for the provided agent ID
creatorId	string	Filter to only coaching sessions created by the provided user ID
coachId	string	Filter to only coaching sessions where the coach matches the provided user ID
startDate	date string (see formats)	Filter to only coaching sessions created after the provided date
endDate	date string (see formats)	Filter to only coaching sessions created before the provided date
count	integer	The number of results to return
startIndex	integer	Offset to start pagination search results

Response

Name	Type	Description
startIndex	integer	Offset of paginated search results
totalResults	integer	Total number of coaching points that match the provided query filters
itemsPerPage	integer	The number of results per page
Resources	array[coaching sessions]	List of coaching sessions matching the filter criteria

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/coaching-sessions'
params = {
    'count': 3,
    'coachId': 'zme7PkariKd5Hb4fT',
    'startDate': '2023-06-01T15:08:45.781Z',
    'endDate': '2023-08-01T15:08:45.781Z',
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, params=params, headers=headers)

Example Response

{
    "startIndex": 0,
    "totalResults": 253,
    "itemsPerPage": 3,
    "Resources": [
        {
            "id": "25oWGcmSd34yZRR84",
            "name": "Sample Coaching Session",
            "createdAt": "2023-07-13T16:02:42.255Z",
            "updatedAt": "2023-07-13T16:02:53.622Z",
            "agentId": "72999",
            "agentName": "Harrison Charles",
            "coachId": "zme7PkariKd5Hb4fT",
            "coachName": "Charlie Smith",
            "creatorId": "zme7PkariKd5Hb4fT",
            "agentNotes": "Agent's notes",
            "coachNotes": "Coach's notes",
            "coachPrivateNotes": "Private (not shared with agent) notes",
            "sessionContents": "Contents of the sessions's 'Overview' tab",
            "coachingTemplateId": "16906fb5ce9d57646fa38362",
            "meetingFormat": "inPerson",
            "agentConfirmed": false,
            "coachConfirmed": false
        },
        {
            "id": "2BNoiJDcthvabPyxC",
            "name": "Created by Matthew",
            "createdAt": "2023-06-22T21:09:25.511Z",
            "updatedAt": "2023-07-26T21:05:24.878Z",
            "agentId": "0055e000000ZIqdAAG",
            "agentName": "Automated Process",
            "coachId": "zme7PkariKd5Hb4fT",
            "coachName": "Matthew Chuck",
            "creatorId": "zme7PkariKd5Hb4fT",
            "agentNotes": "",
            "coachNotes": "",
            "coachPrivateNotes": "",
            "sessionContents": "Performance\nAgent perspective on their performance since last review\nHow do you feel about your recent performance?\nHave you been experiencing any blockers in your workflow? Is there any additional support you need?\n\nGrowth\nDiscuss areas that the Agent has grown or excelled in. How has this contributed to their overall performance and their team’s?\n \n \n\nDevelopment Goals\nWhat career goals do you want to achieve in the coming quarter or year? What skills or competencies do you want to hone in on?\n\nThis Coming Quarter\n \n \n\nThis Coming Year\n \n \n\n",
            "coachingTemplateId": "16906fb5ce9d57646fa38362_3",
            "meetingFormat": "inPerson",
            "agentConfirmed": false,
            "coachConfirmed": false
        },
        {
            "id": "2BendGuN7JqrKfRGn",
            "name": "test coaching session",
            "createdAt": "2023-06-03T04:02:13.764Z",
            "updatedAt": "2023-06-03T04:02:30.120Z",
            "agentId": "72999",
            "agentName": "Harrison Hunter Rill",
            "coachId": "zme7PkariKd5Hb4fT",
            "coachName": "Harrison Hunter2",
            "creatorId": "zme7PkariKd5Hb4fT",
            "agentNotes": "",
            "coachNotes": "",
            "coachPrivateNotes": "",
            "sessionContents": "",
            "coachingTemplateId": "16906fb5ce9d57646fa38362_2",
            "meetingFormat": "inPerson",
            "agentConfirmed": false,
            "coachConfirmed": true
        }
    ]
}

Rate Limits

A given token has limits on how many times it can be used to make a request. These limits are subject to change, but there are guidelines to follow:

Demanding endpoints (such as requesting an export)

1 request per second

30 requests per minute

Easy endpoints (such as retrieving an export’s status and data url)

10 requests per second

100 requests per minute

You can expect to export 10,000 to 50,000 scores at time. The exact number is variable based on the size of your scorecard, number of comments per scorecard, and other factors.

Error Responses

Common error response scenarios:

401 Unauthorized
- cause: invalid API token
404 Not Found
- likely cause: request made for non-existent content (for example, making a "Get User" request for a user that has been deleted)
409 Conflict
- likely cause: a non-unique value was provided for a parameter that must be unique (for example, making "Create Agent" request with an email that is already in use by an existing agent)
  - the error response message will indicate which values were in conflict
422 Unprocessable Content
- likely cause: invalid values provided for one or more request parameters
  - the error response message will indicate which parameters were invalid
429 Too Many Requests
- cause: exceeded rate limit

Troubleshooting

"Body Parameters" is not be confused with "Query Parameters". For example when using Postman, see the below screenshots clarifying the difference,

Query Parameters:

Body Parameters:

Overview

Table of Contents

Authentication

Obtaining an API Token

Authenticating Requests

Formats

Endpoints

Request A “Raw” Export

Retrieve the results of an export

Request an “agent groups” export

Request an “audit logs” export

Create a Ticket

Update a Ticket

Delete a Ticket

Create a Ticket Comment

Create an Attachment

Create an Agent

Update an Agent (add agent id to agent)

Update an Agent (update agent availability)

Retrieve a Single To-do

Retrieve To-dos

Retrieve a Single Coaching Point

Retrieve Coaching Points

Retrieve a Single Coaching Session

Retrieve Coaching Sessions

Rate Limits

Error Responses

Troubleshooting