Conversations

Explains APIs available to interact with Conversation objects in Score.

List conversations

get

This endpoint will list conversations that have completed evaluation. Pagination is supported using limit and offset query parameters.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · int32 · max: 50Optional

The number of conversations to return. Defaults to 10. Max is 50.

Default: 10

offsetinteger · int32Optional

The number of conversations to skip in pagination. Defaults to 0.

Default: 0

conversationDateFromstring · date-timeOptional

ISO-8601 formatted date-time string for the earliest conversation date

conversationDateTostring · date-timeOptional

ISO-8601 formatted date-time string for the latest conversation date

analysisDateFromstring · date-timeOptional

ISO-8601 formatted date-time string for the earliest analysis date

analysisDateTostring · date-timeOptional

ISO-8601 formatted date-time string for the latest analysis date

Responses

200

The request has succeeded.

application/json

get

/api/v1/conversations

HTTPcURLJavaScriptPython

GET /api/v1/conversations HTTP/1.1
Host: api.usescore.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

The request has succeeded.

{
  "data": {
    "total": 1,
    "items": [
      {
        "id": "text",
        "teamId": "text",
        "playbookScore": 1,
        "speechScore": 1,
        "durationSeconds": 1,
        "conversationType": "text",
        "conversationDate": "2025-12-11T01:59:39.594Z",
        "conversationDescriptor": "text",
        "createdAt": "2025-12-11T01:59:39.594Z",
        "representative": {
          "id": "text",
          "username": "text",
          "name": "text",
          "createdAt": "2025-12-11T01:59:39.594Z"
        }
      }
    ],
    "paging": {
      "limit": 1,
      "offset": 1
    }
  }
}

Get conversation by ID

get

This endpoint allows you get the compete evaluation result for a single conversation.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

conversationIdstringRequired

Responses

200

The request has succeeded.

application/json

get

/api/v1/conversations/{conversationId}

HTTPcURLJavaScriptPython

GET /api/v1/conversations/{conversationId} HTTP/1.1
Host: api.usescore.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

The request has succeeded.

{
  "data": {
    "id": "text",
    "teamId": "text",
    "conversationType": "CALL",
    "playbookScore": 1,
    "speechScore": 1,
    "durationSeconds": 1,
    "conversationDate": "2025-12-11T01:59:39.594Z",
    "conversationDescriptor": "text",
    "conversationHighlights": "text",
    "pace": 1,
    "disfluencies": 1,
    "longPauses": 1,
    "createdAt": "2025-12-11T01:59:39.594Z",
    "representative": {
      "id": "text",
      "username": "text",
      "name": "text",
      "createdAt": "2025-12-11T01:59:39.594Z"
    },
    "playbookEvaluations": [
      {
        "playbookId": "text",
        "name": "text",
        "parameters": [
          {
            "parameterId": "text",
            "name": "text",
            "value": 1,
            "criteria": [
              {
                "value": "text",
                "criterionId": "text",
                "criterionName": "text",
                "criterionNumber": 1,
                "criterionRemarks": "text",
                "fatal": true
              }
            ]
          }
        ]
      }
    ],
    "customerConcerns": [
      {
        "concern": "text",
        "description": "text"
      }
    ],
    "customFields": [
      {
        "customFieldId": "text",
        "key": "text",
        "label": "text",
        "value": null
      }
    ],
    "sentiments": [
      {
        "type": "NEGATIVE",
        "text": "text",
        "speaker": "text",
        "startAtSeconds": 1,
        "endAtSeconds": 1
      }
    ]
  }
}

Get transcript by conversation ID

get

This endpoint gives you the transcript of the requested conversation.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

conversationIdstringRequired

Responses

200

The request has succeeded.

application/json

get

/api/v1/conversations/{conversationId}/transcript

HTTPcURLJavaScriptPython

GET /api/v1/conversations/{conversationId}/transcript HTTP/1.1
Host: api.usescore.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

The request has succeeded.

{
  "data": {
    "id": "text",
    "languageCode": "text",
    "audioUrl": "text",
    "talkPercentageRep": 1,
    "talkPercentageCustomer": 1,
    "dialogues": [
      {
        "speaker": "text",
        "startAtSeconds": 1,
        "endAtSeconds": 1,
        "text": "text"
      }
    ]
  }
}

List custom fields

get

This endpoint returns all custom fields configured for the organisation.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

The request has succeeded.

application/json

get

/api/v1/conversations/custom-fields

HTTPcURLJavaScriptPython

GET /api/v1/conversations/custom-fields HTTP/1.1
Host: api.usescore.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

The request has succeeded.

{
  "data": {
    "items": [
      {
        "id": "text",
        "label": "text",
        "key": "text",
        "type": "text"
      }
    ]
  }
}

Create custom fields

post

This endpoint allows you to create multiple custom fields for the organisation.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

Responses

200

The request has succeeded.

application/json

post

/api/v1/conversations/custom-fields

HTTPcURLJavaScriptPython

POST /api/v1/conversations/custom-fields HTTP/1.1
Host: api.usescore.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "customFields": [
    {
      "label": "text",
      "key": "text",
      "type": "TEXT"
    }
  ]
}

200

The request has succeeded.

{
  "data": {
    "created": 1,
    "total": 1
  }
}

FAQs

Why are the scores a floating point number?

All scores (such as playbookScore) will be a floating point number between 0 and 1 which allows you to present this score on any scale you like.

For example, to present the score on a scale of 0-5 you can multiply the score value by 5.