> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Evaluator
> Create a new evaluator with its evaluation criteria.
The sum of all non-`strict` criterion weights must equal **exactly 100**. The weight of `strict` criteria is automatically set to `0` regardless of what you send.
The `description` of each criterion is the text the AI uses to evaluate the call. A clear, specific description directly improves evaluation accuracy. For guidance on writing effective criteria, see [Evaluator — criteria](/core/evaluator#criteria).
`language` defaults to `"df"` (auto-detect from audio). See [Evaluator — language](/core/evaluator#language) for supported language codes.
Maximum **20 evaluators** per account and **10 criteria** per evaluator. See [Rate Limits & Quotas](/platform/rate-limits).
## OpenAPI
````yaml api-reference/openapi-evaluators.json POST /create-evaluator
openapi: 3.1.0
info:
title: Heify API — Evaluators
description: Endpoints for creating, retrieving, and managing Evaluators.
version: 1.0.0
servers:
- url: https://api.heify.com
security:
- apiKeyAuth: []
paths:
/create-evaluator:
post:
summary: Create Evaluator
description: Creates a new evaluator with its evaluation criteria.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEvaluatorRequest'
examples:
CreateWithAllTypes:
summary: Evaluator with all three criterion types
value:
tag: nombre de ejemplo
description: descripcion opcional
language: df
context: >-
You are evaluating a salesperson during a sales call or
meeting with a prospect or client. Assess their ability to
identify needs, communicate value and handle objections.
criteria:
- name: Cierre de Venta
description: >-
El agente debe solicitar explicitamente la venta o el
compromiso del cliente utilizando tecnicas de cierre
directas como "¿Procedemos con la contratacion?" o "¿Le
gustaria activar el servicio hoy?". No debe finalizar la
llamada sin haber intentado cerrar al menos una vez.
type: boolean
weight: 50
- name: Escucha Activa
description: >-
El agente no interrumpe al cliente mientras expone su
problema, confirma los datos clave repitiendo o
parafraseando lo escuchado y realiza preguntas
relevantes para entender la situacion completa antes de
ofrecer una solucion.
type: strict
weight: 0
- name: Empatia
description: >-
El agente muestra comprension ante la situacion del
cliente utilizando frases de reconocimiento como
"Entiendo su frustracion", "Lamento las molestias" o
"Comprendo lo importante que es esto para usted". No
debe minimizar el problema ni usar un tono
condescendiente.
type: scale
weight: 50
responses:
'201':
description: Evaluator created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEvaluatorResponse'
examples:
Success:
summary: Evaluator created
value:
data:
message: Evaluator created successfully
evaluator:
evaluator_id: 47e865ea-67ee-4930-9064-0a07db10c6b3
tag: nombre de ejemplo
description: descripcion opcional
language: df
context: >-
You are evaluating a salesperson during a sales call
or meeting with a prospect or client. Assess their
ability to identify needs, communicate value and
handle objections.
criteria:
- id: f5ccfa19-40d1-4d0c-aee5-4217a5a22485
name: Cierre de Venta
description: >-
El agente debe solicitar explicitamente la
venta...
type: boolean
weight: 50
- id: beaac9a5-a067-4413-9721-874e3ccda50c
name: Escucha Activa
description: El agente no interrumpe al cliente...
type: strict
weight: 0
- id: 0daee516-3b0f-40b5-836e-f0850365d355
name: Empatia
description: >-
El agente muestra comprension ante la situacion
del cliente...
type: scale
weight: 50
created_at: '2026-03-21T14:19:57.834336+00:00'
components:
schemas:
CreateEvaluatorRequest:
type: object
properties:
tag:
type: string
description: Name/label for the evaluator. Max 100 characters.
description:
type: string
nullable: true
maxLength: 250
description: Description of the evaluator's purpose. Max 250 characters.
language:
type: string
default: df
description: >-
Language for AI evaluation output. `"df"` (default) auto-detects
from audio. See [Evaluator — language](/core/evaluator#language) for
supported codes.
context:
type: string
nullable: true
maxLength: 1000
description: >-
Additional context provided to the AI during evaluation. Helps the
model understand the business scenario. Max 1000 characters.
criteria:
type: array
items:
$ref: '#/components/schemas/CriterionInput'
description: >-
List of evaluation criteria. Min 1, max 10 items. Non-`strict`
weights must sum to exactly 100.
required:
- tag
- criteria
CreateEvaluatorResponse:
type: object
properties:
data:
type: object
properties:
message:
type: string
example: Evaluator created successfully
evaluator:
$ref: '#/components/schemas/EvaluatorObject'
CriterionInput:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 100
description: Name of the criterion. 1–100 characters.
description:
type: string
minLength: 5
maxLength: 2000
description: >-
Detailed instructions for the AI on how to evaluate this criterion.
5–2000 characters. Quality of this description directly affects
evaluation accuracy.
type:
type: string
enum:
- boolean
- scale
- strict
default: boolean
description: >-
`boolean` — pass/fail (0% or 100%); `scale` — scored 1–5; `strict` —
critical pass/fail that triggers a critical fail flag if failed,
regardless of overall score.
weight:
type: integer
minimum: 0
maximum: 100
description: >-
Relative importance in the final score (0–100). Must be > 0 for
non-`strict` criteria. Automatically forced to `0` for `strict`
criteria.
required:
- name
- description
EvaluatorObject:
type: object
description: Full evaluator object as returned by the API.
properties:
evaluator_id:
type: string
format: uuid
description: Unique identifier for this evaluator.
tag:
type: string
description: Name/label for the evaluator (e.g. campaign name).
description:
type: string
nullable: true
description: Description of the evaluator's purpose.
language:
type: string
description: >-
Language used for AI evaluation output. `"df"` = auto-detect from
audio.
context:
type: string
nullable: true
description: Additional context provided to the AI during evaluation.
criteria:
type: array
items:
$ref: '#/components/schemas/CriterionObject'
description: Evaluation criteria for this evaluator.
created_at:
type: string
description: Creation timestamp (ISO 8601).
CriterionObject:
type: object
description: >-
A criterion as returned in API responses. Identical to the input shape
but includes an auto-generated `id`.
properties:
id:
type: string
format: uuid
description: Auto-generated unique identifier for this criterion.
name:
type: string
description: Name of the criterion.
description:
type: string
description: Evaluation instructions provided to the AI.
type:
type: string
enum:
- boolean
- scale
- strict
description: Criterion evaluation type.
weight:
type: integer
description: Weight in the final score. Always `0` for `strict` criteria.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````