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.
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 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 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 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 specific user by userid
id required | string The id of the user to retrieve |
Returns the specified user
Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.
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 key and secret are correct. Every API call requires Basic Auth.
User 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 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 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 roles within EvaluAgent. Useful for assigning roles to users.
Returns an array of roles
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 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 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 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 key and secret are correct. Every API call requires Basic Auth.
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.