Download OpenAPI specification:Download
You can use the EvaluAgent API to access and update information within your EvaluAgent account. The Evaluagent API is organised around REST. REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term ‘REST API’, they are generally referring to an API accessed using the HTTP protocol at a predefined set of URLs.
These URLs represent various resources which can be returned as JSON, HTML or audio files. Often resources have one or more methods that can be performed on them over HTTP
, like GET
, POST
, PUT
and DELETE
. These actions action represent the verbs Fetch, Create, Update and Delete respectively for those resources. The Evaluagent API is structured using the JSON:API specification and described using the OpenAPI specification.
In order to maintain data sovereignty our API can only be accessed regionally by cluster.
For customers on our European cluster (eu-west-1) the API URL is api.evaluagent.com
.
For customers on our North America cluster (us-east) the API URL is api.us-east.evaluagent.com
.
For customers on our Australian cluster (aus) the API URL is api.aus.evaluagent.com
.
/quality/contacts
endpoint.third_party_id
property to the users endpointsLearn how to get started with the Evaluagent API. This article describes how to quickly get started with the Evaluagent API using curl
and Basic Authentication.
curl
if it isn't already installed on your machine. To check if curl
is installed, execute curl --version
in the command line. If the output is information about the version of curl
, it is installed. If you get a message similar to command not found: curl
, you need to download and install curl
. More information can be found here.curl
command to make your request. Pass your token in an Authorization header. Replace YOUR-ACCESS-KEY-ID and YOU-SECRET-KEY with your Access Key ID and Secret Key respectively. curl –request GET --url "https://YOUR-CLUSTER-REGION/v1/org/users" -u "YOUR-ACCESS-KEY-ID:YOUR-SECRET-KEY"
All API access is over HTTPS and via regional clusters
All data is sent and received as JSON.
Blank fields are included as null
instead of being omitted.
All timestamps return as a String in UTC time, ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and potentially a response body. The REST API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation.
To make a request, first find the HTTP method and the path for the operation that you want to use. For example, the "List users" operation uses the GET
method and the /org/users
path. Prepend the base URL for the Evaluagent API region (for example: https://api.evaluagent.com
in Europe) and then the version (currently v1
) to the path to get the full URL. For example: https://api.evaluagent.com/v1/org/users
in Europe.
Evaluagent supports HTTP Basic authentication. API keys can be provisioned in the Evaluagent platform under Conversations>>Integrations>>API. These are needed to authenticate requests against the API.
You must pass your Access Key ID and Secret Key in an Authorization header with every request to the API in the format "Basic YOUR-ACCESS-KEY-ID:YOUR-SECRET-KEY"
, where YOUR-ACCESS-KEY-ID:YOUR-SECRET-KEY
are Base64 encoded. Many HTTP clients will automatically format in this way for you.
Alternatively, you can use the details above to generate a Bearer Token. These expire every 24 hours unless they are refreshed, providing a new token and invaliding the existing token. Once a token has been generated, Basic Authentication will be disabled for those credentials.
Ping our API to verify your current authentication details
Returns authentication information
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Token has been created
Unauthorized. Check your API credentials.
Forbidden. Bearer Tokens can only be created using Basic Auth.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Invalidate the bearer token used for authentication. Please be aware that the basic authentication details that worked to create this token will continue to be unusable. This is a destructive action which will prevent future API requests associated with this key
Token has been successfully revoked (empty body response)
Unauthorized. Check your API credentials.
Forbidden. Must use Token authentication.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
This will issue a new bearer token associated with this API key, the bearer token used for authentication will be invalidated upon issue of the new token
Token has been refreshed (the previous token is no longer valid)
Unauthorized. Check your API credentials.
Forbidden. Must use Token authentication.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Use this endpoint to add a new user to your Evaluagent org.
Add a user to your Evaluagent org.
Define the Roles for this User using the Roles relationship. This can include making the user an Agent, Quality Analyst or Administrator as well as granting login access to the EvaluAgent app. A list of role ids can be found in the Roles endpoint.
If the created user is an Agent then the optional 'agent-team' relationship can be used to specify the id of the Group that they belong to. The list of Groups can be fetched using the Groups endpoint.
data | object |
Returns the new user
Validation errors
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of all the users in this org. Filter by email address to search for a specific user.
filter[email] | string <string> Example: filter[email]=user%40company.com Return a specific user by their email address. |
filter[username] | string <string> Example: filter[username]=user%40company.com Return a specific user by their username. |
Returns an array of users
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a specific user by userid
id required | string The id of the user to retrieve |
Returns the specified user
Unauthorized. Check your API credentials.
User not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Update a user's details
Toggle state between active/deactive setting the 'active' attribute.
Define the Roles for this User using the Roles relationshop. This can include making the user an Agent, Quality Analyst or Administrator as well as granting login access to the EvaluAgent app. A list of role ids can be found in the Roles endpoint.
If the user is an Agent then the 'agent-team' relationship can be updated to move the Agent to a different group. The list of groups can be fetched using the Groups endpoint.
id required | string The id of the user to update |
Updated details for the user
data | object |
Returns the updated user
Validation failure
Unauthorized. Check your API credentials.
User not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Use this endpoint to add a new group to your Evaluagent org.
Add a group to your Evaluagent org. Levels can be grabbed from the org/levels endpoint.
data | object |
Returns the new group
Validation errors
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of your groups and their hierarchy within EvaluAgent. Useful for compiling a list of groups and their ids for managing agents.
show_inactive | boolean Whether inactive groups should be shown. Defaults to false. |
Returns an array of groups
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Update a group's details
id required | string The id of the group to update |
Updated details for the group
data | object |
Returns the updated group
Validation failure
Unauthorized. Check your API credentials.
Group not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Delete group
id required | string The ID of the group to retrieve |
Returns nothing. Group has been deleted.
Unauthorized. Check your API credentials.
Group not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Use this endpoint to add a new Role to your Evaluagent org.
Add a role to your Evaluagent org. Abilities can be grabbed from the org/abilities endpoint.
data | object |
Returns the new role
Validation errors
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of your roles within EvaluAgent. Useful for assigning roles to users.
Returns an array of roles
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Update a role's details
id required | string The id of the role to update |
Updated details for the role
data | object |
Returns the updated role
Validation failure
Unauthorized. Check your API credentials.
Role not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Delete role
id required | string The ID of the role to retrieve |
Returns nothing. Role has been deleted.
Unauthorized. Check your API credentials.
Role not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of your levels within EvaluAgent. Useful for creating groups.
Returns an array of levels
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of your abilities within EvaluAgent. Useful for creating roles.
Returns an array of abilities
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of your completed evaluations and their results.
The request can be filtered by date and sorted by published_at
, date_published
, updated_at
, reference
, score
, agent_name
, evaluator_name
. The endpoint also supports pagination, requests default to the first page. If you also need the related contacts for the evaluations then use
include
to also return those contacts with the request.
filter[published_at;between] | string <date-time> Example: filter[published_at;between]=2023-05-01T00%3A00%3A00.000Z%2C%202023-08-01T00%3A00%3A00.000Z A date range to filter evaluations on their |
sort | string Example: sort=-published_at An option to sort by order of choice. Adding a minus operator to the start of field you wish to sort on will return results descending order. List of sorting options - |
page[number] | number Example: page[number]=1 When paginated, the page number that you would like to request. Defaults to 1. |
include | string Example: include=contacts Request that contacts associated with the returned evaluations be included under the "included" key in the response. |
Returns an array of evaluations
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a detailed view of an evaluation, including feedback and individual line item scores.
Use include
to also return related contacts and evaluators or agents for this specific evaluation.
id required | string The id of the evaluation to retrieve |
include | Array of strings Items Enum: "contact" "evaluator" "agent" Example: include=contact,evaluator,agent A comma-separated list of records associated with the evaluation to be included under the "included" key in the response. Available record types are contact, evaluator, and agent. |
Returns the evaluation
Unauthorized. Check your API credentials.
Evaluation not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Use this endpoint to import conversations from other platforms into Evaluagent.
/quality/imported-contacts/upload-audio
endpoint to upload that audio file. Then using the returned path
reference use this endpoint to import the related metadata for your conversation.Please note there is rate-limiting in place for this endpoint. Maximum 100 requests per-minute, based on API credentials.
Contact to add to EvaluAgent.
data | object |
Your imported contact was successfully created in EvaluAgent.
Validation errors
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Use this endpoint to import recorded audio file conversations from other platforms into Evaluagent.
Use the path
reference in the response from this endpoint when importing the related metadata with the /quality/imported-contacts
endpoint.
The Evaluagent platform supports all audio encoded in a format supported by HTML5
audio_file required | null <binary> The audio file to upload. Must be an MP3, WAV, OGG, M4A, etc. |
Your audio file was successfully uploaded to EvaluAgent.
Validation errors
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch conversational analytics for contacts between a specified time period
filter[contact_date;between] required | string <date-time> Example: filter[contact_date;between]=2023-05-01T00%3A00%3A00.000Z%2C%202023-05-31T00%3A00%3A00.000Z A date range to filter conversations on their |
filter[insight_topics][] | array <string> Example: filter[insight_topics][]=13686037-e52e-470a-966c-843437e7d422 An array of topic UUIDs to filter conversations by |
sort | string Example: sort=-contact_date An option to sort by order of choice. Adding a minus operator to the start of field you wish to sort on will return results descending order. List of sorting options - |
page[number] | number Example: page[number]=1 When paginated, the page number that you would like to request. Defaults to 1. |
Returns an array of conversational analytics records
Validation errors
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch conversational analytics for a specific contact
id required | string The id of the conversation to retrieve |
Returns analytics for a single conversation
Unauthorized. Check your API credentials.
Conversation not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of Work Queue Templates in this org.
Returns a list of Work Queue Templates
Unauthorized. Check your API credentials.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a specific Work Queue Template by ID
id required | string The ID of the Work Queue Template to retrieve |
Returns the specified Work Queue Template
Unauthorized. Check your API credentials.
Work Queue Template not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a specific Work Queue Template by the given ID
id required | string The ID of the Work Queue Template to retrieve |
Returns the agents assigned to the specified Work Queue Template
Unauthorized. Check your API credentials.
Work Queue Template not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Sync Agents assigned to the given Work Queue Template. Agents assigned to the Work Queue Template will be updated to match the given data, removing any assigned agents if not included in the data.
id required | string The ID of the Work Queue Template to retrieve |
Returns the updated Work Queue Template
Unauthorized. Check your API credentials.
Work Queue Template not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Add agents assigned to the Work Queue Template
id required | string The ID of the Work Queue Template to retrieve |
Returns the updated Work Queue Template
Unauthorized. Check your API credentials.
Work Queue Template not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Delete Agents assigned to the given Work Queue Template
id required | string The ID of the Work Queue Template to retrieve |
Returns the updated Work Queue Template
Unauthorized. Check your API credentials.
Work Queue Template not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of 121 Topics specific to the API Key's contract.
Returns a list of 121 Topics
Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Fetch a list of your 121s and associated details.
The request can be filtered by date and sorted by published_at
, date_published
, created_at
, updated_at
, reference
, score
, agent_name
, evaluator_name
.
The endpoint also supports pagination, requests default to the first page.
filter[created_at;between] | string <date-time> Example: filter[created_at;between]=2023-05-01T00%3A00%3A00.000Z%2C%202023-08-01T00%3A00%3A00.000Z A date range to filter 121s on their created_at date. Consists of a comma-separated start and end date in UTC format. |
filter[scheduled_date;between] | string <date-time> Example: filter[scheduled_date;between]=2023-05-01T00%3A00%3A00.000Z%2C%202023-08-01T00%3A00%3A00.000Z A date range to filter 121s on their scheduled_date. Consists of a comma-separated start and end date in UTC format. |
filter[completed_at;between] | string <date-time> Example: filter[completed_at;between]=2023-05-01T00%3A00%3A00.000Z%2C%202023-08-01T00%3A00%3A00.000Z A date range to filter 121s on their completed_at date. Consists of a comma-separated start and end date in UTC format. |
filter[participant] | string Example: filter[participant]=99abbc05-9535-4e20-84be-0d4e55bcd407 Unique user ID to filter 121 participants by |
filter[facilitator] | string Example: filter[facilitator]=99abbc05-9535-4e20-84be-0d4e55bcd407 Unique user ID to filter 121 facilitators by |
sort | string Enum: "scheduled_date" "started_at" "completed_at" "topic" "participant" Example: sort=-scheduled_date Sort the returned 121s. Adding a minus operator to the start of field you wish to sort on will return results descending order. |
page[number] | number Example: page[number]=1 When paginated, the page number that you would like to request. Defaults to 1. |
Returns an array of evaluations
Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Create a new 121
Create a new 121
data | object |
Returns an object containing details for the newly-created 121.
Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Retrieve details for a single 121.
id | string Example: 99abbc05-9535-4e20-84be-0d4e55bcd407 Unique identifier for a single 121 record |
Returns an object containing details for the 121 requested.
Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.
121 not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Update the 121 with the specified details
Updated details for the 121
data | object |
Returns an object containing details for the updated 121.
Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.
121 not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster
Delete the specified 121
No response.
Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.
121 not found
Customers on our EU cluster
Customers on our Australian cluster
Customers on our North American (US-East) cluster