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 plain-text transcript (with speaker labels) or a .txt / .json / .html file, 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. 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

Form fields

* Exactly one of file or rawText is required per request.

Request

# Score a transcript file
curl -X POST https://platform.openknowra.ai/api/bff/v1/ai-agents/call-quality-manager/upload \
  -H "Authorization: Bearer $OPENKNOWRA_API_KEY" \
  -F "file=@/path/to/transcript.txt"

# Score raw transcript text
curl -X POST https://platform.openknowra.ai/api/bff/v1/ai-agents/call-quality-manager/upload \
  -H "Authorization: Bearer $OPENKNOWRA_API_KEY" \
  -F "rawText=AGENT: Thank you for calling. How can I help you today?
CUSTOMER: 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/ai-agents/call-quality-manager/upload"

def score_transcript(file_path: str) -> dict:
    with open(file_path, "rb") as f:
        res = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": f},
        )
    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()

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

import fs from "fs";

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

async function scoreTranscript(filePath: string) {
  const form = new FormData();
  const buffer = fs.readFileSync(filePath);
  form.append("file", new Blob([buffer]), "transcript.txt");

  const res = await fetch(API_URL, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
    body: form,
  });

  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("./call_transcript.txt");
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": "cq_7f3a9b2c",
  "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": [
      { "label": "Empathy & Tone",          "score": 10, "maxScore": 12 },
      { "label": "First Call Resolution",   "score": 11, "maxScore": 14 },
      { "label": "Compliance Checklist",    "score": 10, "maxScore": 12 },
      { "label": "Active Listening",        "score":  8, "maxScore": 10 },
      { "label": "Product / Plan Accuracy", "score":  9, "maxScore": 12 },
      { "label": "Solution Orientation",    "score":  8, "maxScore": 10 },
      { "label": "Brand / Upsell",          "score":  7, "maxScore": 10 },
      { "label": "Conversation Closure",    "score":  9, "maxScore": 10 },
      { "label": "Sentiment Delta",         "score":  7, "maxScore": 10 }
    ]
  },
  "newBalance": 875
}

Grade bands

Nine scoring dimensions

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.

curl -X POST https://platform.openknowra.ai/api/bff/v1/ai-agents/call-quality-manager/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-..."
}

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 rawText field in a subsequent upload request.

Bulk scoring

Score up to 100 transcripts in a single request instead of calling /upload 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/ai-agents/call-quality-manager/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": "cq_9d21ab77", "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.

Errors

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