logo
API docs by Redocly

EvaluAgent API (1.0.6)

Download OpenAPI specification:Download

Support: support@evaluagent.com URL: https://support.evaluagent.com

Introduction

Evaluagent API

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.

Changelog

21st January 2025

  • Add integration as a required query parameter to the analytics/conversations endpoint

4th Sep 2024

  • Added rate-limiting to all endpoints. Maximum is 100 requests per minute, 10,000 per day, per API key, per endpoint.

5th August 2024

  • Added ping endpoint for authentication details
  • Added support for bearer tokens

12th July 2024

  • Added endpoint to retrieve analytics for a single conversation

08th July 2024

  • Added conversational analytics reporting endpoint

14th March 2024

  • Added Levels Index, Abilities Index, Groups CUD, Roles CUD

30th August 2023

  • Added additional details on Authentication

28th March 2023

  • Added 'scorecard_id' to evaluations list and single evaluation endpoints

21st Feb 2023

  • Added the 'agent' relationship to evaluations in the 'List evaluations' endpoint

2nd February 2023

  • Imported Contacts endpoint: Added metadata array example

31st January 2023

  • Improved documentation content & layout.
  • Deprecated /quality/contacts endpoint.

13th December 2022

  • Imported Contacts endpoint: removed requirement for a responses array or audio file path.

2 December 2022

  • Added third_party_id property to the users endpoints

19th October 2022

  • New endpoint for generating an Imported Contact
  • New endpoint for uploading audio files

8th September 2022

  • On the List Groups endpoint, added an additional attribute to indicate if the group was a part of the "Custom Reporting Groups" feature.

3rd August 2022

  • Added the ability to import third-party contacts.

26th April 2022

  • Added the property 'started_at' to the Evaluation resource.

15th November 2021

  • The users endpoint can now return an individual user via filter search string.

13th October 2021

  • Added the US-East cluster endpoint

2nd March 2021

  • Added the outcome_name property to Evaluations. This will contain the manual outcome if manual outcomes are in use, otherwise it will contain the name of the outcome configured by the user in Quality Settings.

24th September 2020

  • Added the seconds_elapsed property to Evaluations

28th May 2020

  • Added required tags to appropriate attributes in Create a Contact

5th March 2020

  • Added new sorting options for evaluations
  • Root causes will now appear with evaluations if present
  • Data capture responses will now appear with evaluations if present
  • Adding a new metadata property to Contacts which can include additional, third party information

QuickStart

Learn 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.

  1. Install 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.
  2. Create an Evaluagent API key in Conversations>>Integrations>>API. Take a note of the Access Key ID and Secret Key. Warning: Treat your API key like a password.
  3. Use the 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"

Overview

API version

Available resources may vary between REST API versions. The current version is V1.

Schema

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

Guides

Using the API

About the Evaluagent API

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.

Making a request

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.

Basics of authentication

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.

Bearer Token Authentication

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

Check authentication status

Ping

Ping our API to verify your current authentication details

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "ping": "2024-01-01 00:00:00",
  • "ip": "127.0.0.1",
  • "bearer": {
    }
}

Tokens

Create, refresh, or expire Bearer Tokens for authentication

Create Token

Authorizations:
Basic

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "expiration": "2024-01-01 00:00:00"
}

Revoke Token

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

Authorizations:
Bearer

Responses

Refresh Token

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

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "expiration": "2024-01-01 00:00:00"
}

Users

Fetch, create and update users

Create a user

Use this endpoint to add a new user to your Evaluagent org.

Authorizations:
BasicBearer
Request Body schema: application/json
required

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.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List users

Fetch a list of all the users in this org. Filter by email address to search for a specific user.

Authorizations:
BasicBearer
query Parameters
filter[email]
string <string>
Example: filter[email]=user@company.com

Return a specific user by their email address.

filter[username]
string <string>
Example: filter[username]=user@company.com

Return a specific user by their username.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Fetch a user

Fetch a specific user by userid

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the user to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an existing user

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.

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the user to update

Request Body schema: application/json
required

Updated details for the user

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Groups

List your group hierarchy

Create a group

Use this endpoint to add a new group to your Evaluagent org.

Authorizations:
BasicBearer
Request Body schema: application/json
required

Add a group to your Evaluagent org. Levels can be grabbed from the org/levels endpoint.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List groups

Fetch a list of your groups and their hierarchy within EvaluAgent. Useful for compiling a list of groups and their ids for managing agents.

Authorizations:
BasicBearer
query Parameters
show_inactive
boolean

Whether inactive groups should be shown. Defaults to false.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update an existing group

Update a group's details

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the group to update

Request Body schema: application/json
required

Updated details for the group

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete group

Delete group

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the group to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": null
}

Roles

List user roles

Create a role

Use this endpoint to add a new Role to your Evaluagent org.

Authorizations:
BasicBearer
Request Body schema: application/json
required

Add a role to your Evaluagent org. Abilities can be grabbed from the org/abilities endpoint.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List roles

Fetch a list of your roles within EvaluAgent. Useful for assigning roles to users.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update an existing role

Update a role's details

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the role to update

Request Body schema: application/json
required

Updated details for the role

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete role

Delete role

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the role to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": null
}

Levels

List levels

Fetch a list of your levels within EvaluAgent. Useful for creating groups.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Abilities

List abilities

Fetch a list of your abilities within EvaluAgent. Useful for creating roles.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Evaluations

List and query evaluations

List evaluations

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.

Authorizations:
BasicBearer
query Parameters
filter[published_at;between]
string <date-time>
Example: filter[published_at;between]=2023-05-01T00:00:00.000Z, 2023-08-01T00:00:00.000Z

A date range to filter evaluations on their published_at date. Consists of a comma-separated start and end date in UTC format.

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 - published_at, date_published, updated_at, reference, score, agent_name, evaluator_name

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.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Fetch an evaluation

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.

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the evaluation to retrieve

query Parameters
include
Array of strings
Items Enum: "contact" "evaluator" "agent"
Example: include=contact&include=evaluator&include=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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Imported Contacts

Import conversations and contacts from external platforms into EvaluAgent

Generate an imported contact

Use this endpoint to import conversations from other platforms into Evaluagent.

  • For text-only conversations use this endpoint as is.
  • For conversations that include a recorded audio file you will need to first use the /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.

Authorizations:
BasicBearer
Request Body schema: application/json
required

Contact to add to EvaluAgent.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Success",
  • "contact_reference": "a63e026f-50ea-42c8-9fa1-418b4427a10c",
  • "3rd_party_reference": "contact001"
}

Upload audio

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

Authorizations:
BasicBearer
Request Body schema: multipart/form-data
audio_file
required
null <binary>

The audio file to upload. Must be an MP3, WAV, OGG, M4A, etc.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Audio file uploaded successfully",
  • "path": "quality/fb2db7c0-de00-43ed-997d-f587eac8bdbb/55649393-f708-4ebf-a665-a39942c030f1.mp3"
}

Conversational Analytics

Retrieve analytics data for your conversations over a specified period

Get Conversational Analytics

Fetch conversational analytics for contacts between a specified time period

Authorizations:
BasicBearer
query Parameters
filter[integration]
required
string
Example: filter[integration]=8fa6239b-14a6-4d40-8afe-398312f779f6

The UUID of the integration to return

filter[contact_date;between]
required
string <date-time>
Example: filter[contact_date;between]=2023-05-01T00:00:00.000Z, 2023-05-31T00:00:00.000Z

A date range to filter conversations on their contact_date. Consists of a comma-separated start and end date in UTC format.

filter[insight_topics][]
Array of arrays
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 - contact_date

page[number]
number
Example: page[number]=1

When paginated, the page number that you would like to request. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Conversation

Fetch conversational analytics for a specific contact

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the conversation to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
  • "type": "conversational_analytics",
  • "attributes": {
    }
}

Templates

List Work Queue Templates

Fetch a list of Work Queue Templates in this org.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Fetch a Work Queue Template

Fetch a specific Work Queue Template by ID

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch Agents assigned to a Work Queue Template

Fetch a specific Work Queue Template by the given ID

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update Agents assigned to a Work Queue Template

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.

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Add Agents assigned to a Work Queue Template

Add agents assigned to the Work Queue Template

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete Agents assigned to a Work Queue Template

Delete Agents assigned to the given Work Queue Template

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Topics

Manage 121 Topics

List 121 Topics

Fetch a list of 121 Topics specific to the API Key's contract.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

One To Ones

View & manage your 121s

List 121s

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.

Authorizations:
BasicBearer
query Parameters
filter[created_at;between]
string <date-time>
Example: filter[created_at;between]=2023-05-01T00:00:00.000Z, 2023-08-01T00:00:00.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:00:00.000Z, 2023-08-01T00:00:00.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:00:00.000Z, 2023-08-01T00:00:00.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.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create 121

Create a new 121

Authorizations:
BasicBearer
Request Body schema: application/json
required

Create a new 121

object (BaseOneToOneParameters)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "one-to-ones",
  • "attributes": {
    },
  • "relationships": {
    }
}

Fetch 121

Retrieve details for a single 121.

Authorizations:
BasicBearer
path Parameters
id
string
Example: 99abbc05-9535-4e20-84be-0d4e55bcd407

Unique identifier for a single 121 record

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "one-to-ones",
  • "attributes": {
    },
  • "relationships": {
    }
}

Update 121

Update the 121 with the specified details

Authorizations:
BasicBearer
Request Body schema: application/json
required

Updated details for the 121

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "one-to-ones",
  • "attributes": {
    },
  • "relationships": {
    }
}

Delete 121

Delete the specified 121

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": null
}