Call Quality Assessment API

When to use this API

Use this API when you need a consistent, auditable quality score for a customer-care call transcript without building your own scoring pipeline.

The API accepts a JSON body carrying the transcript as plain text (with speaker labels), runs it through the nine-dimension Service Excellence Index, and returns a structured result: overall score (0-100), grade letter (A+ to E), per-dimension scores with rule-level observations, call-type classification, and sentiment delta. If your transcript lives in a .txt, .json, or .html file, read it client-side first (HTML tags stripped) and send its text content as the transcript field — /upload is kept as an alias of this same endpoint for callers migrating from the older agent-page name. Language is auto-detected transcripts in Hindi, Tamil, Telugu, Kannada, Malayalam, Marathi, or Punjabi are translated to English for scoring and the original language is preserved in the response.

Authentication

All requests require a user-scoped API key passed as a bearer token. Generate one in the platform under Settings → API Keys. Keys are prefixed ok_ and expire after 90 days.

Authorization: Bearer ok_xxxxxxxxxxxxxxxxxxxxxxxx

Parameters

JSON body fields

Request

# NOTE: transcript must be a single-line string — escape newlines as \n
curl -X POST https://platform.openknowra.ai/api/bff/v1/call-quality-assessment/analyze \
  -H "Authorization: Bearer $OPENKNOWRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript":"AGENT: Thank you for calling. How can I help you today?\nCUSTOMER: Hi, I have an issue with my bill."}'

import os
import requests

API_KEY = os.environ["OPENKNOWRA_API_KEY"]
API_URL = "https://platform.openknowra.ai/api/bff/v1/call-quality-assessment/analyze"

def score_transcript(transcript: str) -> dict:
    res = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"transcript": transcript},
    )
    if res.status_code == 402:
        err = res.json()["error"]
        raise ValueError(
            f"Insufficient credits: need {err['required']}, have {err['balance']}"
        )
    res.raise_for_status()
    return res.json()

with open("./call_transcript.txt") as f:
    result = score_transcript(f.read())

assessment = result["assessment"]
print(f"Grade: {assessment['grade']}  Score: {assessment['overallScore']}/100")
for factor in assessment.get("factors", []):
    print(f"  {factor['label']}: {factor['raw']}/{factor['max']}")

const API_KEY = process.env.OPENKNOWRA_API_KEY!;
const API_URL = "https://platform.openknowra.ai/api/bff/v1/call-quality-assessment/analyze";

async function scoreTranscript(transcript: string) {
  const res = await fetch(API_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ transcript }),
  });

  if (res.status === 402) {
    const err = await res.json() as { error: { required: number; balance: number } };
    throw new Error(
      `Insufficient credits: need ${err.error.required}, have ${err.error.balance}`
    );
  }

  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

const result = await scoreTranscript(
  "AGENT: Thank you for calling. How can I help you today?\nCUSTOMER: Hi, I have an issue with my bill."
);
const { grade, overallScore, factors } = result.assessment;
console.log(`Grade: ${grade}  Score: ${overallScore}/100`);
console.log(JSON.stringify(factors, null, 2));

Response

200 OK Returns the scored call with overall grade, nine-dimension factor breakdown, call metadata, and sentiment delta.

{
  "callId": "SE-CALL-a1b2c3d4e5f6",
  "idempotent": false,
  "assessment": {
    "overallScore": 79,
    "grade": "B",
    "decision": "meets_standard",
    "coachingPriority": "low",
    "language": "en",
    "callType": { "id": "CMPL", "label": "Complaint" },
    "subCategory": { "id": "CMPL.BIL", "label": "Billing Dispute" },
    "turnCount": 18,
    "agentTurnCount": 9,
    "customerTurnCount": 9,
    "talkToListenRatio": 48,
    "talkToListenBand": "balanced",
    "customerSentimentLabel": "positive",
    "sentimentTrend": "improving",
    "outcomeLabel": "resolved",
    "factors": [
      {
        "key": "empathy", "label": "Empathy & Tone", "raw": 10, "max": 12,
        "percentScore": 83, "summary": "Strong empathetic tone throughout.",
        "observations": [
          { "rule": "empathy_phrase_hit", "matched": true, "count": 3, "description": "Used empathetic acknowledgements 3 times." }
        ]
      },
      { "key": "fcr",        "label": "First Call Resolution",   "raw": 11, "max": 14, "percentScore": 79, "observations": [] },
      { "key": "compliance", "label": "Compliance Checklist",    "raw": 10, "max": 12, "percentScore": 83, "observations": [] },
      { "key": "listening",  "label": "Active Listening",        "raw":  8, "max": 10, "percentScore": 80, "observations": [] },
      { "key": "accuracy",   "label": "Product / Plan Accuracy", "raw":  9, "max": 12, "percentScore": 75, "observations": [] },
      { "key": "solution",   "label": "Solution Orientation",    "raw":  8, "max": 10, "percentScore": 80, "observations": [] },
      { "key": "brand",      "label": "Brand / Upsell",          "raw":  7, "max": 10, "percentScore": 70, "observations": [] },
      { "key": "closure",    "label": "Conversation Closure",    "raw":  9, "max": 10, "percentScore": 90, "observations": [] },
      { "key": "sentiment",  "label": "Sentiment Delta",         "raw":  7, "max": 10, "percentScore": 70, "observations": [] }
    ]
  },
  "newBalance": 875
}

Each factor's score lives in raw/max (not score/maxScore — that pair only appears on historical assessments returned by GET /calls/{'{'}id{'}'}, once persisted). percentScore, summary, and rule-level observations are computed on every response.

Grade bands

Nine scoring dimensions

Pricing

Credits are charged per MB of transcript (ceiling'd, minimum 1 MB) at a rate gated by language, not a flat per-call fee. Rates are configurable per workspace and can drift from these defaults — call GET /pricing to read the live, currently configured figures rather than hardcoding them.

{
  "textEnPerMb": 5,
  "textNonEnPerMb": 8,
  "audioPerMinute": 3,
  "coachRewritePerMb": 7,
  "creditPriceUsd": 0.1
}

Dashboard KPIs

Every scored response includes derived analytics fields alongside the factors array. These do not affect overallScore they are surface labels computed from the transcript for client-facing dashboards.

Audio Transcription (optional)

When you have a call recording instead of a ready-made transcript, use the two-step audio pipeline. The API uploads the file to AWS Transcribe, performs speaker diarization, and returns a AGENT: / CUSTOMER: transcript you can pass straight to the upload endpoint.

Step 1 : Upload audio

Send as multipart/form-data. The uploaded file is pushed straight to S3 and a Transcribe job is started. Billed at 3 credits per minute of audio (ceiling'd, no free allowance) — duration is measured from the uploaded file itself, deducted before the job starts and refunded if the upload or job start fails. See Pricing.

curl -X POST https://platform.openknowra.ai/api/bff/v1/call-quality-assessment/transcribe-upload \
  -H "Authorization: Bearer $OPENKNOWRA_API_KEY" \
  -F "audio=@call_recording.mp3"

{
  "jobName":         "se-call-1719388800000-a1b2c3d4",
  "s3Key":           "se-transcribe/inbox/1719388800000-a1b2c3d4.mp3",
  "mediaFormat":     "mp3",
  "languageCode":    "en-US",
  "status":          "IN_PROGRESS",
  "message":         "Transcription started · poll GET /transcribe-job/se-call-...",
  "durationSeconds": 187,
  "creditsCharged":  9,
  "newBalance":      866
}

Step 2 : Poll job status

{
  "status":     "COMPLETED",
  "language":   "en-US",
  "transcript": "AGENT: Thank you for calling. How can I help?\nCUSTOMER: Hi, I have an issue with my bill.",
  "turns": [
    { "speaker": "Agent",    "startMs": 0,    "endMs": 2400, "text": "Thank you for calling. How can I help?" },
    { "speaker": "Customer", "startMs": 2800, "endMs": 5100, "text": "Hi, I have an issue with my bill." }
  ]
}

When status is IN_PROGRESS, the response contains only { "status": "IN_PROGRESS", "language": "..." } poll again after a few seconds. Transcription typically completes in 30-90 seconds for a 10-minute call. Pass the returned transcript string as the transcript field in a subsequent analyze request. Scoring it is billed separately at the text rate — "transcribe once, score once", no extra flat surcharge for the audio path.

Bulk scoring

Score up to 100 transcripts in a single request instead of calling /analyze once per transcript.

# transcripts is an array of strings and/or objects up to 100 per request
curl -X POST https://platform.openknowra.ai/api/bff/v1/call-quality-assessment/bulk-upload \
  -H "Authorization: Bearer $OPENKNOWRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcripts": [
      "AGENT: Thank you for calling...\nCUSTOMER: Hi, I am calling about...",
      { "transcript": "AGENT: Hello!\nCUSTOMER: I want to upgrade my plan...", "categoryId": "SALE" }
    ]
  }'

{
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "results": [
    { "index": 0, "ok": true, "callId": "SE-CALL-9d21ab77e5f6", "assessment": { "overallScore": 74, "grade": "B", "decision": "meets_standard", "coachingPriority": "low", "factors": [ /* ... */ ] } },
    { "index": 1, "ok": true, "unscorable": true, "reason": "This transcript is not a scorable agent-customer conversation (too short, or missing a real two-sided exchange). Provide a fuller call with AGENT: and CUSTOMER: turns." }
  ],
  "newBalance": 850
}

The platform's own Bulk Upload UI additionally accepts .json files (a single object, or an array of items in the same shape above) and .zip files (bundling multiple .txt/.html/.json entries, including sub-folders one transcript per file, or many if a .json entry holds an array); the same 100 transcripts / 25 MB limit applies whether you use that UI or call the API directly as shown above.

Additional endpoints

Free, unmetered helper endpoints for building a scoring UI, plus a way to re-fetch a previously scored call — none of these deduct credits except /coach-rewrite.

All paths above are relative to /v1/call-quality-assessment.

Errors

{
  "error": {
    "code":     "insufficient_credits",
    "required": 25,
    "balance":  10
  }
}