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
.
integration
as a required query parameter to the analytics/conversations
endpoint/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.
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
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": "string",
- "expiration": "2024-01-01 00:00:00"
}
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.
object |
{- "data": {
- "type": "users",
- "attributes": {
- "forename": "John",
- "surname": "Smith",
- "email": "john.smith@example.com",
- "username": "john.smith@example.com",
- "active": true,
- "allow_login": true,
- "reporting_access_id": "ec1cf0c7-d90e-4988-b6f2-f9624eb4a5b5",
- "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"
}
]
}
}
}
}
{- "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": "2019-08-24T14:15:22Z",
- "active": true,
- "allow_login": true,
- "reporting_access_id": "ec1cf0c7-d90e-4988-b6f2-f9624eb4a5b5",
- "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 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@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. |
{- "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": "2019-08-24T14:15:22Z",
- "active": true,
- "allow_login": true,
- "reporting_access_id": "ec1cf0c7-d90e-4988-b6f2-f9624eb4a5b5",
- "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 specific user by userid
id required | string The id of the user to retrieve |
{- "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": "2019-08-24T14:15:22Z",
- "active": true,
- "allow_login": true,
- "reporting_access_id": "ec1cf0c7-d90e-4988-b6f2-f9624eb4a5b5",
- "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 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
object |
{- "data": {
- "type": "users",
- "attributes": {
- "forename": "John",
- "surname": "Smith",
- "email": "john.smith@example.com",
- "username": "john.smith@example.com",
- "active": true,
- "allow_login": true,
- "reporting_access_id": "ec1cf0c7-d90e-4988-b6f2-f9624eb4a5b5",
- "third_party_id": "idFromExternalSystem"
}, - "relationships": {
- "agent-team": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "groups"
}
}, - "roles": {
- "data": [
- {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "roles"
}
]
}
}
}
}
{- "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": "2019-08-24T14:15:22Z",
- "active": true,
- "allow_login": true,
- "reporting_access_id": "ec1cf0c7-d90e-4988-b6f2-f9624eb4a5b5",
- "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"
}
]
}
}
}
}
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.
object |
{- "data": {
- "type": "groups",
- "attributes": {
- "name": "Agent",
- "level": "7e1ff821-b744-417b-a212-58ed46457b31",
- "active": true,
- "parent_group": "8d1ef891-g744-417d-h212-58er47547d81"
}
}
}
{- "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
}
}
}
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. |
{- "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
}
}
]
}
Update a group's details
id required | string The id of the group to update |
Updated details for the group
object |
{- "data": {
- "type": "groups",
- "attributes": {
- "name": "Agent",
- "level": "7e1ff821-b744-417b-a212-58ed46457b31",
- "active": true,
- "parent_group": "8d1ef891-g744-417d-h212-58er47547d81"
}
}
}
{- "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
}
}
}
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.
object |
{- "data": {
- "type": "roles",
- "attributes": {
- "name": "Agent"
}, - "relationships": {
- "abilities": {
- "data": [
- {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "abilities"
}
]
}
}
}
}
{- "data": {
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "roles",
- "attributes": {
- "title": "Team Leader",
- "name": "team-leader"
}, - "relationships": {
- "abilities": {
- "data": [
- {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "abilities"
}
]
}
}
}
}
Fetch a list of your roles within EvaluAgent. Useful for assigning roles to users.
{- "data": [
- {
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "roles",
- "attributes": {
- "title": "Team Leader",
- "name": "team-leader"
}, - "relationships": {
- "abilities": {
- "data": [
- {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "abilities"
}
]
}
}
}
]
}
Update a role's details
id required | string The id of the role to update |
Updated details for the role
object |
{- "data": {
- "type": "roles",
- "attributes": {
- "name": "Admin"
}, - "relationships": {
- "abilities": {
- "data": [
- {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "abilities"
}
]
}
}
}
}
{- "data": {
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "roles",
- "attributes": {
- "title": "Team Leader",
- "name": "team-leader"
}, - "relationships": {
- "abilities": {
- "data": [
- {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "abilities"
}
]
}
}
}
}
Fetch a list of your abilities within EvaluAgent. Useful for creating roles.
{- "data": [
- {
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "abilities",
- "attributes": {
- "heading": "User Management Permissions",
- "title": "Manage Users"
}
}
]
}
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:00:00.000Z, 2023-08-01T00:00:00.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. |
{- "data": [
- {
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "evaluations",
- "attributes": {
- "published_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "notes": "string",
- "mode": "Official Evaluation",
- "status": "string",
- "scorecard": "Customer Service Scorecard v1",
- "scorecard_id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "outcome": "Pass",
- "outcome_name": "Fair",
- "num_of_autofails": 0,
- "quality_score": "87.4",
- "seconds_elapsed": 1776,
- "started_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "evaluator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "contact": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "contacts"
}
}, - "agent": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "agents"
}
}
}
}
]
}
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&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. |
{- "data": {
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "evaluations",
- "attributes": {
- "published_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "notes": "string",
- "mode": "Official Evaluation",
- "status": "string",
- "scorecard": "Customer Service Scorecard v1",
- "scorecard_id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "outcome": "Pass",
- "outcome_name": "Fair",
- "num_of_autofails": 0,
- "quality_score": "87.4",
- "seconds_elapsed": 1776,
- "started_at": "2019-08-24T14:15:22Z",
- "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": "2019-08-24T14:15:22Z"
}
]
}, - "relationships": {
- "evaluator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "contact": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "contacts"
}
}, - "agent": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "agents"
}
}
}
}
}
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.
object |
{- "data": {
- "reference": "string",
- "agent_id": "string",
- "agent_email": "string",
- "contact_date": "2019-08-24T14:15:22Z",
- "channel": "Email",
- "assigned_at": "2019-08-24T14:15:22Z",
- "solved_at": "2019-08-24T14:15:22Z",
- "handling_time": 120,
- "customer_telephone_number": "01753 877212",
- "audio_file_path": "string",
- "metadata": {
- "Direction": "inbound",
- "Campaign": "new-campaign"
}, - "responses": [
- {
- "speaker_id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "speaker_email": "string",
- "response_id": "515235",
- "message": "Hi, I’ve been trying to resolve an issue regarding my online account.",
- "channel": "Email",
- "message_created_at": "2022-09-01T00:00:00Z",
- "speaker_is_customer": true
}
]
}
}
{- "status": 200,
- "message": "Success",
- "contact_reference": "a63e026f-50ea-42c8-9fa1-418b4427a10c",
- "3rd_party_reference": "contact001"
}
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. |
{- "status": 200,
- "message": "Audio file uploaded successfully",
- "path": "quality/fb2db7c0-de00-43ed-997d-f587eac8bdbb/55649393-f708-4ebf-a665-a39942c030f1.mp3"
}
Fetch conversational analytics for contacts between a specified time period
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 |
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 - |
page[number] | number Example: page[number]=1 When paginated, the page number that you would like to request. Defaults to 1. |
{- "data": [
- {
- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "conversational_analytics",
- "attributes": {
- "contact_date": "2019-08-24T14:15:22Z",
- "3rd_party_reference": "ABC123",
- "source_id": 123456,
- "channel": "Salesforce",
- "agent_id": "string",
- "agent_name": "John Smith",
- "handle_time": 306,
- "response_count": 12,
- "has_audio": true,
- "silence_duration": 62,
- "overtalk_instances": 2,
- "xnps_outcome": "string",
- "reason_for_contact": "string",
- "sentiment": {
- "sentiment_score": 0,
- "agent_sentiment_label": "string",
- "agent_sentiment_score": 0,
- "customer_sentiment_label": "string",
- "customer_sentiment_score": 0
}, - "ai": {
- "ai_opening": "string",
- "ai_requirements": "string",
- "ai_discussion": "string",
- "ai_outcome": "string"
}, - "topics": "{'Topic Name': 'Pass', 'Another Topic': 'Fail', 'Final Topic': ''}"
}
}
]
}
Fetch conversational analytics for a specific contact
id required | string The id of the conversation to retrieve |
{- "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
- "type": "conversational_analytics",
- "attributes": {
- "contact_date": "2019-08-24T14:15:22Z",
- "3rd_party_reference": "ABC123",
- "source_id": 123456,
- "channel": "Salesforce",
- "agent_id": "string",
- "agent_name": "John Smith",
- "handle_time": 306,
- "response_count": 12,
- "has_audio": true,
- "silence_duration": 62,
- "overtalk_instances": 2,
- "xnps_outcome": "string",
- "reason_for_contact": "string",
- "sentiment": {
- "sentiment_score": 0,
- "agent_sentiment_label": "string",
- "agent_sentiment_score": 0,
- "customer_sentiment_label": "string",
- "customer_sentiment_score": 0
}, - "ai": {
- "ai_opening": "string",
- "ai_requirements": "string",
- "ai_discussion": "string",
- "ai_outcome": "string"
}, - "topics": "{'Topic Name': 'Pass', 'Another Topic': 'Fail', 'Final Topic': ''}"
}
}
Fetch a list of Work Queue Templates in this org.
{- "data": [
- {
- "id": "8cba1b19-4cbb-4247-8ed4-6f94753c56d6",
- "type": "template",
- "attributes": {
- "name": "My Work Queue Template",
- "status": "active",
- "cycle_type": "daily",
- "cycle_value": 1,
- "cycle_month_day": 15,
- "created_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "agent": {
- "data": [
- {
- "id": "c98c1599-7f9d-4206-92f5-85e5dd2576e8",
- "type": "users"
}, - {
- "id": "2c63916a-1591-48a8-8584-9efd30dc3178",
- "type": "users"
}
]
}
}
}
]
}
Fetch a specific Work Queue Template by ID
id required | string The ID of the Work Queue Template to retrieve |
{- "data": {
- "id": "8cba1b19-4cbb-4247-8ed4-6f94753c56d6",
- "type": "template",
- "attributes": {
- "name": "My Work Queue Template",
- "status": "active",
- "cycle_type": "daily",
- "cycle_value": 1,
- "cycle_month_day": 15,
- "created_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "agent": {
- "data": [
- {
- "id": "c98c1599-7f9d-4206-92f5-85e5dd2576e8",
- "type": "users"
}, - {
- "id": "2c63916a-1591-48a8-8584-9efd30dc3178",
- "type": "users"
}
]
}
}
}
}
Fetch a specific Work Queue Template by the given ID
id required | string The ID of the Work Queue Template to retrieve |
{- "data": [
- {
- "type": "users",
- "id": "154d0f4a-d274-4660-87be-077443297638"
}
]
}
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 |
{- "data": [
- {
- "type": "users",
- "id": "154d0f4a-d274-4660-87be-077443297638"
}
]
}
Add agents assigned to the Work Queue Template
id required | string The ID of the Work Queue Template to retrieve |
{- "data": [
- {
- "type": "users",
- "id": "154d0f4a-d274-4660-87be-077443297638"
}
]
}
Delete Agents assigned to the given Work Queue Template
id required | string The ID of the Work Queue Template to retrieve |
{- "data": [
- {
- "type": "users",
- "id": "154d0f4a-d274-4660-87be-077443297638"
}
]
}
Fetch a list of 121 Topics specific to the API Key's contract.
{- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "one-to-one-topics",
- "attributes": {
- "name": "string",
- "active": true,
- "colour": "string"
}
}
]
}
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: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. |
{- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "one-to-ones",
- "attributes": {
- "location": "string",
- "reference": "string",
- "started_at": null,
- "created_at": null,
- "scheduled_date": null,
- "completed_at": null,
- "description": "string",
- "prep_notes": "string",
- "acknowledgement_time": null,
- "facilitator_comments": "string",
- "participant_comments": "string",
- "online_meeting": true,
- "status": "string",
- "private": true,
- "participant_can_view_before": true,
- "duration_hours": 0,
- "duration_minutes": 0,
- "end_datetime_from_duration": null,
- "total_duration_minutes": 0,
- "third_party_id": 0,
- "date": null
}, - "relationships": {
- "facilitator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "participant": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "topic": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_topics"
}
}, - "actions": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_actions"
}
}
}
}
]
}
Create a new 121
Create a new 121
object (BaseOneToOneParameters) |
{- "data": {
- "type": "one-to-ones",
- "attributes": {
- "duration_hours": 0,
- "duration_minutes": 0,
- "duration_location": "string",
- "meeting_config": {
- "meet_now": true
}, - "participant_can_view_before": true,
- "private": true,
- "started_at": null,
- "status": "completed_acknowledged",
- "timezone": "Europe/London",
- "type": "face-to-face"
}, - "relationships": {
- "facilitator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "participant": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "topic": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_topics"
}
}, - "actions": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_actions"
}
}
}
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "one-to-ones",
- "attributes": {
- "location": "string",
- "reference": "string",
- "started_at": null,
- "created_at": null,
- "scheduled_date": null,
- "completed_at": null,
- "description": "string",
- "prep_notes": "string",
- "acknowledgement_time": null,
- "facilitator_comments": "string",
- "participant_comments": "string",
- "online_meeting": true,
- "status": "string",
- "private": true,
- "participant_can_view_before": true,
- "duration_hours": 0,
- "duration_minutes": 0,
- "end_datetime_from_duration": null,
- "total_duration_minutes": 0,
- "third_party_id": 0,
- "date": null
}, - "relationships": {
- "facilitator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "participant": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "topic": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_topics"
}
}, - "actions": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_actions"
}
}
}
}
Retrieve details for a single 121.
id | string Example: 99abbc05-9535-4e20-84be-0d4e55bcd407 Unique identifier for a single 121 record |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "one-to-ones",
- "attributes": {
- "location": "string",
- "reference": "string",
- "started_at": null,
- "created_at": null,
- "scheduled_date": null,
- "completed_at": null,
- "description": "string",
- "prep_notes": "string",
- "acknowledgement_time": null,
- "facilitator_comments": "string",
- "participant_comments": "string",
- "online_meeting": true,
- "status": "string",
- "private": true,
- "participant_can_view_before": true,
- "duration_hours": 0,
- "duration_minutes": 0,
- "end_datetime_from_duration": null,
- "total_duration_minutes": 0,
- "third_party_id": 0,
- "date": null
}, - "relationships": {
- "facilitator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "participant": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "topic": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_topics"
}
}, - "actions": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_actions"
}
}
}
}
Update the 121 with the specified details
Updated details for the 121
object |
{- "data": {
- "type": "one-to-ones",
- "attributes": {
- "duration_hours": 0,
- "duration_minutes": 0,
- "duration_location": "string",
- "meeting_config": {
- "meet_now": true
}, - "participant_can_view_before": true,
- "private": true,
- "started_at": null,
- "status": "completed_acknowledged",
- "timezone": "Europe/London",
- "type": "face-to-face"
}, - "relationships": {
- "facilitator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "participant": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "topic": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_topics"
}
}, - "actions": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_actions"
}
}
}, - "id": "string"
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "one-to-ones",
- "attributes": {
- "location": "string",
- "reference": "string",
- "started_at": null,
- "created_at": null,
- "scheduled_date": null,
- "completed_at": null,
- "description": "string",
- "prep_notes": "string",
- "acknowledgement_time": null,
- "facilitator_comments": "string",
- "participant_comments": "string",
- "online_meeting": true,
- "status": "string",
- "private": true,
- "participant_can_view_before": true,
- "duration_hours": 0,
- "duration_minutes": 0,
- "end_datetime_from_duration": null,
- "total_duration_minutes": 0,
- "third_party_id": 0,
- "date": null
}, - "relationships": {
- "facilitator": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "participant": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "users"
}
}, - "topic": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_topics"
}
}, - "actions": {
- "data": {
- "id": "ea0c8aab-dc5b-4d7e-b2bc-364250679278",
- "type": "one_to_one_actions"
}
}
}
}