EvaluAgent API (1.0.5)

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.

Change log

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.

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

Europe: https://api.evaluagent.com.
North America: https://api.us-east.evaluagent.com.
Australia: https://api.aus.evaluagent.com.

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 "YOUR-ACCESS-KEY-ID:YOUR-SECRET-KEY".

Authentication

Basic Auth with Evaluagent API Key

HTTP Basic Auth using API Key & Secret

Security scheme type:	HTTP
HTTP Authorization Scheme	basic

Users

Fetch, create and update users

Create a user

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

Authorizations:

Basic Auth with Evaluagent API Key

Request Body schema: application/json

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

Responses

201

Returns the new user

400

Validation errors

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

post /org/users

Customers on our EU cluster

https://api.evaluagent.com/v1/org/users

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/org/users

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/org/users

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"data":
{
- "type": "users",
- "attributes":
  {
  - "forename": "John",
  - "surname": "Smith",
  - "email": "john.smith@example.com",
  - "username": "john.smith@example.com",
  - "active": true,
  - "third_party_id": 12345
  },
- "relationships":
  {
  - "agent-team":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "groups"
    }
    },
  - "roles":
    {
    "data":
    [
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "roles"
    }
    ]
    }
  }
}

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
{
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "users",
- "attributes":
  {
  - "forename": "John",
  - "surname": "Smith",
  - "email": "john.smith@example.com",
  - "username": "john.smith@example.com",
  - "start_date": "2023-02-03T11:43:28Z",
  - "active": true,
  - "third_party_id": "someOtherId"
  },
- "relationships":
  {
  - "agent-team":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "groups"
    }
    },
  - "roles":
    {
    "data":
    [
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "roles"
    }
    ]
    }
  }
}

}

List users

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

Authorizations:

Basic Auth with Evaluagent API Key

query Parameters

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.

Responses

200

Returns an array of users

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

get /org/users

Customers on our EU cluster

https://api.evaluagent.com/v1/org/users

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/org/users

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/org/users

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
[
- {
  - "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
  - "type": "users",
  - "attributes":
    {
    "forename": "John",
    "surname": "Smith",
    "email": "john.smith@example.com",
    "username": "john.smith@example.com",
    "start_date": "2023-02-03T11:43:28Z",
    "active": true,
    "third_party_id": "someOtherId"
    },
  - "relationships":
    {
    "agent-team":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "groups"
    }
    },
    "roles":
    {
    "data":
    [
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "roles"
    }
    ]
    }
    }
  }
]

}

Fetch a user

Fetch a specific user by userid

Authorizations:

Basic Auth with Evaluagent API Key

path Parameters

required

string

The id of the user to retrieve

Responses

200

Returns the specified user

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

404

User not found

get /org/users/{id}

Customers on our EU cluster

https://api.evaluagent.com/v1/org/users/{id}

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/org/users/{id}

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/org/users/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
{
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "users",
- "attributes":
  {
  - "forename": "John",
  - "surname": "Smith",
  - "email": "john.smith@example.com",
  - "username": "john.smith@example.com",
  - "start_date": "2023-02-03T11:43:28Z",
  - "active": true,
  - "third_party_id": "someOtherId"
  },
- "relationships":
  {
  - "agent-team":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "groups"
    }
    },
  - "roles":
    {
    "data":
    [
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "roles"
    }
    ]
    }
  }
}

}

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:

Basic Auth with Evaluagent API Key

path Parameters

required

string

The id of the user to update

Request Body schema: application/json

Updated details for the user

data

object

Responses

200

Returns the updated user

400

Validation failure

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

404

User not found

patch /org/users/{id}

Customers on our EU cluster

https://api.evaluagent.com/v1/org/users/{id}

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/org/users/{id}

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/org/users/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"data":
{
- "type": "users",
- "attributes":
  {
  - "forename": "John",
  - "surname": "Smith",
  - "email": "john.smith@example.com",
  - "username": "john.smith@example.com",
  - "active": true
  },
- "relationships":
  {
  - "agent-team":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "groups"
    }
    },
  - "roles":
    {
    "data":
    [
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "roles"
    }
    ]
    }
  }
}

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
{
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "users",
- "attributes":
  {
  - "forename": "John",
  - "surname": "Smith",
  - "email": "john.smith@example.com",
  - "username": "john.smith@example.com",
  - "start_date": "2023-02-03T11:43:28Z",
  - "active": true,
  - "third_party_id": "someOtherId"
  },
- "relationships":
  {
  - "agent-team":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "groups"
    }
    },
  - "roles":
    {
    "data":
    [
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "roles"
    }
    ]
    }
  }
}

}

Groups

List your group hierarchy

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:

Basic Auth with Evaluagent API Key

query Parameters

show_inactive

boolean

Whether inactive groups should be shown. Defaults to false.

Responses

200

Returns an array of groups

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

get /org/groups

Customers on our EU cluster

https://api.evaluagent.com/v1/org/groups

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/org/groups

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/org/groups

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
[
- {
  - "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
  - "type": "groups",
  - "attributes":
    {
    "name": "Customer Service Department",
    "level": "Department",
    "active": true,
    "is_custom_reporting_group": false,
    "parent": "7e1ff821-b744-417b-a212-58ed46457b31",
    "has_children": true
    }
  }
]

}

Roles

List user roles

List roles

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

Authorizations:

Basic Auth with Evaluagent API Key

Responses

200

Returns an array of roles

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

get /org/roles

Customers on our EU cluster

https://api.evaluagent.com/v1/org/roles

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/org/roles

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/org/roles

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
[
- {
  - "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
  - "type": "roles",
  - "attributes":
    {
    "title": "Team Leader",
    "name": "team-leader"
    }
  }
]

}

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:

Basic Auth with Evaluagent API Key

query Parameters

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 `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

200

Returns an array of evaluations

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

get /quality/evaluations

Customers on our EU cluster

https://api.evaluagent.com/v1/quality/evaluations

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/quality/evaluations

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/quality/evaluations

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
[
- {
  - "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
  - "type": "evaluations",
  - "attributes":
    {
    "published_at": "2023-02-03T11:43:28Z",
    "updated_at": "2023-02-03T11:43:28Z",
    "notes": "string",
    "mode": "Official Evaluation",
    "status": "string",
    "scorecard": "Customer Service Scorecard v1",
    "outcome": "Pass",
    "outcome_name": "Fair",
    "num_of_autofails": 0,
    "quality_score": "87.4",
    "seconds_elapsed": 1776,
    "started_at": "2023-02-03T11:43:28Z"
    },
  - "relationships":
    {
    "evaluator":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "users"
    }
    },
    "contact":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "contacts"
    }
    }
    }
  }
]

}

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:

Basic Auth with Evaluagent API Key

path Parameters

required

string

The id of the evaluation to retrieve

query Parameters

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.

Responses

200

Returns the evaluation

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

404

Evaluation not found

get /quality/evaluations/{id}

Customers on our EU cluster

https://api.evaluagent.com/v1/quality/evaluations/{id}

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/quality/evaluations/{id}

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/quality/evaluations/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"data":
{
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "evaluations",
- "attributes":
  {
  - "published_at": "2023-02-03T11:43:28Z",
  - "updated_at": "2023-02-03T11:43:28Z",
  - "notes": "string",
  - "mode": "Official Evaluation",
  - "status": "string",
  - "scorecard": "Customer Service Scorecard v1",
  - "outcome": "Pass",
  - "outcome_name": "Fair",
  - "num_of_autofails": 0,
  - "quality_score": "87.4",
  - "seconds_elapsed": 1776,
  - "started_at": "2023-02-03T11:43:28Z",
  - "category_results":
    [
    {
    "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
    "name": "Customer Experience",
    "result": "100.0"
    }
    ],
  - "evaluation_feedback":
    [
    {
    "type": "Neutral",
    "feedback": "Feedback for agent"
    }
    ],
  - "line_items":
    [
    {
    "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
    "name": "Did the agent open the call correctly?",
    "categories":
    [
    {
    "name": "Customer Experience"
    }
    ],
    "weighting": "1",
    "auto_fail_setting": false,
    "score": "0.5",
    "outcome_title": "Exceeds",
    "system_outcome": "Pass",
    "line_item_feedback":
    [
    {
    "type": "Neutral",
    "feedback": "Feedback for agent"
    }
    ],
    "root_cause": "Agent did not get marketing permissions"
    }
    ],
  - "data_capture_responses":
    [
    {
    "id": "8c752858-02ce-473a-b1ef-47a5c42c76a5",
    "question_id": "3568d086-f228-4c03-af4b-52bb5c90794b",
    "question_text": "Branch location",
    "answer": "London",
    "is_freetext": false,
    "created_at": "2023-02-03T11:43:28Z"
    }
    ]
  },
- "relationships":
  {
  - "evaluator":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "users"
    }
    },
  - "contact":
    {
    "data":
    {
    "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "type": "contacts"
    }
    }
  }
}

}

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:

Basic Auth with Evaluagent API Key

Request Body schema: application/json

Contact to add to EvaluAgent.

data

object

Responses

200

Your imported contact was successfully created in EvaluAgent.

400

Validation errors

401

Unauthorized. Check your API key and secret are correct. Every API call requires Basic Auth.

post /quality/imported-contacts

Customers on our EU cluster

https://api.evaluagent.com/v1/quality/imported-contacts

Customers on our Australian cluster

https://api.aus.evaluagent.com/v1/quality/imported-contacts

Customers on our North American (US-East) cluster

https://api.us-east.evaluagent.com/v1/quality/imported-contacts

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"data":
{
- "reference": "string",
- "agent_id": "string",
- "agent_email": "string",
- "contact_date": "2023-02-03T11:43:28Z",
- "channel": "Email",
- "assigned_at": "2023-02-03T11:43:28Z",
- "solved_at": "2023-02-03T11:43:28Z",
- "handling_time": 120,
- "external_url": "https://evaluagent.com",
- "customer_telephone_number": "01753 877212",
- "audio_file_path": "string",
- "metadata": [ ],
- "responses":
  [
  - {
    "speaker_id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
    "speaker_email": "string",
    "response_id": "515235"

EvaluAgent API (1.0.5)

Introduction

Evaluagent API

Change log

2nd February 2023

31st January 2023

13th December 2022

2 December 2022

19th October 2022

8th September 2022

3rd August 2022

26th April 2022

15th November 2021

13th October 2021

2nd March 2021

24th September 2020

28th May 2020

5th March 2020

QuickStart

Overview

API version

Schema

Guides

Using the API

About the Evaluagent API

Making a request

Basics of authentication

Authentication

Basic Auth with Evaluagent API Key

Users

Create a user

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

List users

Authorizations:

query Parameters

Responses

Response samples

Fetch a user

Authorizations:

path Parameters

Responses

Response samples

Update an existing user

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Groups

List groups

Authorizations:

query Parameters

Responses

Response samples

Roles

List roles

Authorizations:

Responses

Response samples

Evaluations

List evaluations

Authorizations:

query Parameters

Responses

Response samples

Fetch an evaluation

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Imported Contacts

Generate an imported contact

Authorizations:

Request Body schema: application/json