Create a Scorecard

Create a new scorecard for evaluating call quality. Scorecards contain categories and criteria that define how calls are scored.

Request

curl -X POST "https://api.chanl.ai/api/v1/scorecards" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quality Scorecard",
    "description": "Evaluates agent performance and call quality",
    "status": "active",
    "passingThreshold": 70
  }'

const response = await fetch('https://api.chanl.ai/api/v1/scorecards', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Quality Scorecard',
    description: 'Evaluates agent performance and call quality',
    status: 'active',
    passingThreshold: 70
  })
});

const { data } = await response.json();
console.log('Created scorecard:', data.id);

import requests

response = requests.post(
    'https://api.chanl.ai/api/v1/scorecards',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'name': 'Quality Scorecard',
        'description': 'Evaluates agent performance and call quality',
        'status': 'active',
        'passingThreshold': 70
    }
)

scorecard = response.json()['data']

Response

{
  "success": true,
  "data": {
    "id": "scorecard_abc123",
    "name": "Quality Scorecard",
    "description": "Evaluates agent performance and call quality",
    "status": "active",
    "version": 1,
    "passingThreshold": 70,
    "createdAt": "2026-01-06T10:00:00Z",
    "updatedAt": "2026-01-06T10:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": ["name: Name is required"]
  }
}

Required Fields

namestringrequired

Name of the scorecard (unique within workspace).

Optional Fields

descriptionstring

Description of what the scorecard evaluates.

statusstringdefault: draft

Status: active, inactive, draft

passingThresholdnumber

Minimum score percentage to pass (0-100).

iconstring

Icon identifier for UI display.

colorstring

Color code for UI display (hex format).

Complete Scorecard Example

After creating a scorecard, add categories and criteria:

{
  "name": "Customer Service Quality",
  "description": "Comprehensive evaluation of customer service calls",
  "status": "active",
  "passingThreshold": 75
}

Then add categories:

POST /api/v1/scorecards/{scorecardId}/categories
{
  "name": "Communication",
  "description": "Evaluates communication skills",
  "weight": 40
}

And criteria:

POST /api/v1/scorecards/{scorecardId}/criteria
{
  "key": "proper_greeting",
  "name": "Proper Greeting",
  "categoryId": "{categoryId}",
  "type": "prompt",
  "settings": {
    "description": "Agent greeted the customer professionally"
  }
}

Scorecard Structure

Scorecard
├── Category: Communication (40%)
│   ├── Criteria: Proper Greeting
│   ├── Criteria: Clear Explanation
│   └── Criteria: Active Listening
├── Category: Resolution (35%)
│   ├── Criteria: Issue Identified
│   └── Criteria: Solution Provided
└── Category: Compliance (25%)
    ├── Criteria: Disclosure Given
    └── Criteria: Verification Complete

Criteria Types

Type	Description
`prompt`	LLM evaluates based on description
`keyword`	Checks for specific words/phrases
`response_time`	Evaluates response latency
`talk_time`	Evaluates talk time metrics
`silence_duration`	Evaluates silence periods
`interruptions`	Counts interruptions
`tool_call`	Checks if tools were used

Required Fields

Optional Fields

Complete Scorecard Example

Scorecard Structure

Criteria Types

On this page