Partner Call Analysis API Documentation

Before you start

Create a server-side API key in Settings

Never expose the key in a browser, mobile app, source repository, ticket, or chat. New keys include both scopes by default: call-analysis:write for agent discovery and uploads, and call-analysis:read for result polling.

Discover and map agents

Every call must belong to an active Callwise agent. Fetch the roster with the same API key, match the partner’s staff record using employee_id, email, or extension, and persist the returned agent_id.

Request

curl "https://callwise.knownsense.ai/api/v1/call-analysis/agents?search=EMP-42&page=1&page_size=50" \
  --header "Authorization: Bearer <api_key>"

Response

{
  "data": [
    {
      "agent_id": "6e93c487-59d8-4c1f-bf5f-ec3c68a5194a",
      "employee_id": "EMP-42",
      "full_name": "Asha Rao",
      "email": "asha@example.com",
      "team": "Retention",
      "extension": "2042",
      "updated_at": "2026-07-13T10:10:00Z"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1 }
}

The endpoint returns active agents only. Use search, page, and page_size (maximum 100). If there is no match, ask a Callwise admin to create or reactivate the agent before uploading.

Upload the call recording

Submit one metadata JSON part and one audio file part. Send a unique Idempotency-Key of 8–128 printable characters so a network retry cannot create a second job.

Multipart request

curl --request POST "https://callwise.knownsense.ai/api/v1/call-analysis/jobs" \
  --header "Authorization: Bearer <api_key>" \
  --header "Idempotency-Key: partner-call-1042" \
  --form 'metadata={
    "external_call_id": "partner-call-1042",
    "agent_id": "6e93c487-59d8-4c1f-bf5f-ec3c68a5194a",
    "contact_number": "+919876543210",
    "lead_name": "Example Lead",
    "direction": "outbound",
    "recording_at": "2026-07-13T10:30:00Z",
    "language_hint": "hi-IN",
    "tags": ["campaign-july"]
  };type=application/json' \
  --form "audio=@call.mp3;type=audio/mpeg"

Field	Type	Requirement
external_call_id	string	Your unique call identifier. Maximum 128 characters.
agent_id	UUID	Required. Use an active agent_id returned by the agents endpoint.
contact_number	string	Customer or lead phone number containing 7–15 digits.
direction	string	Either "inbound" or "outbound".
recording_at	RFC 3339	When the call recording started.
lead_name (optional)	string	Customer or lead name. Maximum 200 bytes.
language_hint (optional)	string	Language hint such as "hi-IN" or "en-IN".
tags (optional)	string[]	Up to 20 tags, each no longer than 64 bytes.

Supported formats include MP3, WAV, M4A/MP4, AAC, AMR, 3GP, OGG/Opus, and FLAC. Maximum audio size is 69 MiB.

202 Accepted

{
  "data": {
    "job_id": "27a57fb0-49f0-4b3a-bc88-32b144a9cd7e",
    "external_call_id": "partner-call-1042",
    "status": "queued",
    "status_url": "/api/v1/call-analysis/jobs/27a57fb0-49f0-4b3a-bc88-32b144a9cd7e",
    "submitted_at": "2026-07-13T10:31:04Z"
  }
}

Poll for analysis results

Poll the returned status_url with read scope. While the job is queued or processing, wait for the response’s Retry-After value before polling again. Add include_transcript=true only when the transcript is needed.

Result request

curl "https://callwise.knownsense.ai/api/v1/call-analysis/jobs/27a57fb0-49f0-4b3a-bc88-32b144a9cd7e?include_transcript=true" \
  --header "Authorization: Bearer <api_key>"

Completed response

{
  "data": {
    "job_id": "27a57fb0-49f0-4b3a-bc88-32b144a9cd7e",
    "external_call_id": "partner-call-1042",
    "status": "completed",
    "stage": "completed",
    "outcome": "success",
    "metadata": {
      "agent_id": "6e93c487-59d8-4c1f-bf5f-ec3c68a5194a",
      "contact_number": "+919876543210",
      "direction": "outbound",
      "recording_at": "2026-07-13T10:30:00Z",
      "tags": ["campaign-july"]
    },
    "result": {
      "summary": "The agent explained the renewal offer and confirmed next steps.",
      "overall_score": 84,
      "sentiment_score": 0.72,
      "keywords": ["renewal", "discount"],
      "recommendations": ["Confirm the callback date explicitly."],
      "duration_seconds": 312,
      "scorecard": { "scores": {}, "summaries": {} },
      "classification": {
        "call_type": "sales",
        "call_reason": "renewal",
        "call_outcome": "follow_up",
        "auto_failed": false,
        "issue": {},
        "speaker_roles": {}
      },
      "flags": [],
      "flags_truncated": false
    },
    "transcript": {
      "full_text": "Agent: Hello... Customer: Yes...",
      "segments": [],
      "word_count": 642,
      "language": "hi-IN",
      "confidence": 0.94
    }
  }
}

queued · accepted
processing · analysis running
completed · result available

Errors and safe retries

HTTP	Code	What to do
400	INVALID_REQUEST / INVALID_METADATA	Fix malformed query parameters, metadata, or multipart content.
401	UNAUTHORIZED	Send a valid Bearer API key.
403	INSUFFICIENT_SCOPE	Use write scope for agent discovery/uploads and read scope for results.
409	DUPLICATE_AUDIO	Reuse the original job or submit a genuinely different recording.
413 / 415	AUDIO_TOO_LARGE / UNSUPPORTED_AUDIO	Keep audio within 69 MiB and use a supported format.
422	INVALID_AGENT	Refresh the agent list and use an active agent from the same tenant.
429	RATE_LIMITED / AGENT_QUOTA_EXCEEDED	Respect Retry-After and retry with backoff.
503	SERVICE_UNAVAILABLE / PIPELINE_PAUSED	Retry later using exponential backoff.

Need an integration check? Contact admin@knownsense.ai with your key prefix and request ID—never send the full API key.

Open Callwise Settings

Send a call. Keep the agent attached.

Before you start

Discover and map agents

Upload the call recording

Poll for analysis results

Errors and safe retries