Skip to content
MoreVoiceDevelopers

Score a call

POST
/calls/{id}/scorecard/run
import MoreVoice from "@morevoice/sdk";


const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment


const scorecard = await mv.qa.run.scorecard("call_7Hk2Lm9Qp", {
  force: false,
});
console.log(scorecard);

Scores the call against its rubric now, even when it is too short for automatic scoring, and answers the scorecard (it can take a few seconds). A call that already has a finished scorecard is not scored again unless force is true. 409 while the call is in progress.

Try it in the API playground with a test-mode key.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
<= 200 characters /^call_[0-9A-Za-z]+$/

A call ID (call_…).

Header Parameters

Section titled “Header Parameters”
MoreVoice-Version
string
/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example
2026-11-01
Idempotency-Key
string
>= 1 characters <= 255 characters

A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.

Example
5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body

Section titled “Request Body”
Media typeapplication/json

Options for scoring.

object
force

Score again even when the call already has a finished scorecard (default false: it is returned as it is).

boolean
Example
{
  "force": false
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A call’s post-call QA scorecard: the rubric’s items scored with verified evidence, compliance, disposition and coaching.

object
call_id
required

A call ID (prefix call_).

string
/^call_[0-9A-Za-z]+$/
coaching
required
Array<object>
object
better
required

What to say instead.

string
tip
required
string
compliance
required
Any of:
object
issues
required
Array<object>
object
detail
required
string
evidence
required
Array<object>
object
line
required

The transcript line (1-based).

integer
>= -9007199254740991 <= 9007199254740991
offset_ms
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
quote
required
string
speaker
required
string
Allowed values: customer agent supervisor other
rule
required
string
severity
required
string
Allowed values: low med high
verdict
required
string
Allowed values: pass warn fail
copilot_profile_id
required
Any of:

A copilot profile ID (prefix cop_).

string
/^cop_[0-9A-Za-z]+$/
created
required

An ISO-8601 timestamp in UTC.

string format: date-time
critical_failed
required

Keys of the critical items that failed the call.

Array<string>
customer_sentiment
required
Any of:
string
Allowed values: positive neutral negative mixed
disposition
required
Any of:
string
Allowed values: sale appointment callback_scheduled follow_up resolved unresolved not_interested escalated wrong_number no_conversation other
error
required
string | null
id
required

The scorecard’s ID (one per call).

string
/^qa_[0-9A-Za-z]+$/
items
required

One per rubric item.

Array<object>
object
critical
required
boolean
evidence
required

Quotes the score rests on, each verified against the transcript.

Array<object>
object
line
required

The transcript line (1-based).

integer
>= -9007199254740991 <= 9007199254740991
offset_ms
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
quote
required
string
speaker
required
string
Allowed values: customer agent supervisor other
key
required

The rubric item’s key.

string
label
required
string
model_score
required

0–5 as the model scored it.

number | null
override
required
Any of:
object
at
required
Any of:

An ISO-8601 timestamp in UTC.

string format: date-time
by
required
string | null
note
required
string | null
score
required
number | null
reasoning
required
string
score
required

0–5 (null: not applicable), after any override.

number | null
weight
required

Relative importance on the 0–100 scale.

number
livemode
required

true in live mode, false in test mode.

boolean
model
required
string | null
model_score
required

0–100 as the model scored it.

number | null
next_steps
required
Array<string>
object
required
string
Allowed value: scorecard
objections
required
Array<object>
object
agent_response
required
string
handled
required
boolean
text
required
string
pass_threshold
required
number | null
passed
required
boolean | null
rubric_source
required
Any of:
string
Allowed values: default copilot_profile
score
required

0–100 after supervisor overrides (null: nothing applicable).

number | null
status
required

skipped: too short to score (error says why); error: scoring failed.

string
Allowed values: pending running done error skipped
strengths
required
Array<string>
summary
required
string | null
updated
required

An ISO-8601 timestamp in UTC.

string format: date-time
Example
{
  "call_id": "call_5Fh7Jk9Lm1Np3Qr5St7Vx9",
  "coaching": [
    {
      "better": "Who else decides on this?",
      "tip": "Confirm the budget owner"
    }
  ],
  "compliance": {
    "issues": [],
    "verdict": "pass"
  },
  "copilot_profile_id": null,
  "created": "2026-11-03T09:16:40.000Z",
  "critical_failed": [],
  "customer_sentiment": "positive",
  "disposition": "appointment",
  "error": null,
  "id": "qa_5Fh7Jk9Lm1Np3Qr5St7Vx9",
  "items": [
    {
      "critical": false,
      "evidence": [
        {
          "line": 7,
          "offset_ms": 41200,
          "quote": "What do you pay today?",
          "speaker": "agent"
        }
      ],
      "key": "discovery",
      "label": "Discovery",
      "model_score": 3,
      "override": {
        "at": "2026-11-03T10:02:00.000Z",
        "by": "Dana Levi",
        "note": "Also asked about the decision maker.",
        "score": 4
      },
      "reasoning": "Asked about the current provider and the budget before the offer.",
      "score": 4,
      "weight": 40
    }
  ],
  "livemode": true,
  "model": "gpt-4.1",
  "model_score": 77.5,
  "next_steps": [
    "Send the demo invite"
  ],
  "object": "scorecard",
  "objections": [
    {
      "agent_response": "Compared it with today's costs.",
      "handled": true,
      "text": "It sounds expensive"
    }
  ],
  "pass_threshold": 70,
  "passed": true,
  "rubric_source": "default",
  "score": 82.5,
  "status": "done",
  "strengths": [
    "Clear opening"
  ],
  "summary": "The customer agreed to a demo on Monday.",
  "updated": "2026-11-03T10:02:00.000Z"
}

400

Section titled “400”

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

401

Section titled “401”

No valid API key was sent.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

403

Section titled “403”

The key may not do this (a missing scope, a plan limit, or a compliance block).

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

404

Section titled “404”

No object with this ID exists in this organisation and mode.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

409

Section titled “409”

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

429

Section titled “429”

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

500

Section titled “500”

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.