Getting Started

This document will guide you through your first automated evaluation via Score's API.

Prerequisites

Ensure you have a valid API key and have understood how to make authenticated API requests by referring to Authentication.

Step 1: Create a representative

Add a representative to your account using the Representative API. The response will contain the created representative object. Save the id of the object for future use.

Step 2: Starting the evaluation of a call

Using the Evaluate API you can trigger the start of an evaluation. For this you will require the following information:

• Conversation

  • Type (conversation.type): Either CALL or EMAIL. This is the discriminator field, i.e., it decides the structure of the rest of conversation object. For the purpose of this guide, we will set this to CALL. See the API reference for how the conversation field changes for other types of conversations.

  • URL (conversation.url): A public link to a call recording. This link should download the audio directly and not load any HTML that plays the video. For example, YouTube links will not work because they load HTML pages.

  • Date (conversation.date): UTC date string (YYYY-MM-DD) for when the call occurred.

  • Descriptor (conversation.descriptor): This is an optional but recommended field that you can send which will be set as the conversation's title. You will be able to search by this value in the in-app conversations page.

• Representative ID: ID of the representative created in the previous step.

Step 3: Polling the progress of the evaluation

The response of the Evaluate API will contain an id which is the ID of the progress record. You can refer to the status field which will be "COMPLETED" when the evaluation has been completed or "ERRORED" when something goes wrong.

In case of any errors during evaluation, the error field will be populated in the progress record which you can refer to for assistance.

Step 4: Checking the conversation

Once evaluation is successfully completed, you can follow any of the two approaches to check the conversation:

1. Using the List Conversations API: Using this API will give you a list of conversations sorted by the analysis dates in descending order. Which means the most recent analysis will be present first.

2. Using the Get Conversation By ID API: The progress record will be populated with a conversationId field when successful. You can use that directly to list the entire conversation details.