Introduction

Transcripto API is a REST interface for integrating with an intelligent system that automatically transcribes calls, analyzes chats, and generates analytical and business reports.

The API enables you to embed customer communication processing directly into your CRM, contact center, or corporate platform — from data ingestion to metrics and ready-to-use visual reports.

How it works

1. Import calls and messages

You can send data in several ways:

uploading an audio file directly (multipart/form-data);
providing a web link to a file (for example, from your CRM cloud storage or an S3 bucket);
sending text dialogs and chats.

The system automatically creates a processing task and stores all data in your account.

2. Speech-to-text

Uploaded audio recordings are transcribed; the system converts speech to text, separates speakers (operator / customer), captures duration, time, and other metadata.

More details: task details · task list by filters

3. Analysis and metric extraction

The AI module analyzes the resulting texts:

identifies topics and intents;
evaluates emotional tone and operator politeness;
checks script and SLA compliance;
detects risks, operator errors, sales opportunities, and more.

Results are stored in the database and exposed via the API as a structured JSON document.

More details: calls_analysis

4. Reports and analytics

Transcripto generates two types of reports:

Operator quality reports over a period — politeness metrics, satisfaction, script compliance, etc.;
Business report for a period — KPIs, trend dynamics, key topics, and recommendations for leadership.

Both report types are available in PDF or HTML and can be easily integrated into a CRM, BI, or internal portals.

Example: Business report

open in a new tab.

Example: Operator quality report

open in a new tab.

How to use the API

Below is a typical integration scenario.

1. Authentication

Obtain an access token:

POST /auth/login

Use it in the Authorization: Bearer <token> header for all subsequent requests.

2. Import calls or chats

Create a call processing task (you can pass either a file or a link):

POST /addtaskcall

POST /addtaskcallbyurl

Create a task to analyze customer text communication: chats, messengers, email threads:

POST /add_chat_analysis_task

The API returns a unique task_code for tracking status, or an error code describing the problem.

3. Check task status

Check the state of a specific task:

GET /gettask?task_code=<GUID>

Get the list of all tasks by the specified filter criteria:

GET /user/tasks/filter

4. Retrieve analytics

After a task of type 'call' (call) or 'chat' (chat) reaches status 'completed' (processing finished), you can request the detailed analysis and the communication text using:

GET /api/calls_analysis/{task_code}

5. Create a report generation task

To download a period report file, create a task with the report type identifier:

 POST /user/callreport

Get the task identifier from the response, track status via gettask, wait for the status to change to 'completed', and in the gettask response obtain the generated file names.

6. Download the report file

Pass the file name to:

# PDF
curl -G "https://<host>/user/callreport/file" \
  --data-urlencode "task_code=<GUID>" \
  --data-urlencode "filename=report_78157.pdf"

# HTML
curl -G "https://<host>/user/callreport/file" \
  --data-urlencode "task_code=<GUID>" \
  --data-urlencode "filename=report_78157.html"

If you need custom analytics and reporting for your customer interaction data, send your request to info@transcripto.ru — we will do our best to implement your requirements.

1) Registration & authentication

User registration

To receive a URL, username, and password to access the Transcripto API, email info@transcripto.ru and include:

Company name, country, city
Industry
Approx. number of calls per day
Approx. number of messages (chats/messengers) per day
Contact phone number, full name

After reviewing your request, you will receive API access credentials: a unique URL, username, and password for authentication.

POST /auth/login

To obtain a token (JWT), call /auth/login — it will return a token for accessing private API methods.

curl -X POST "https://<host>/auth/login" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "email": "user@example.com",
    "password_hash": "2bb80d537b1da3e38bd30361aa855686bde0...<hash>",
    "captcha_token": "<captcha-token>"
  }'

Parameter description (request)

Parameter	Type	Required	Description
email	string	yes	User email.
password_hash	string	yes	User password hash.
captcha_token	string	yes	CAPTCHA token to confirm the request.

{
  "message": "Login successful",
  "error_code": 0,
  "token": "<jwt>",
  "locale": "en",
  "user_id": 83,
  "email": "user@example.com",
  "tariff": {
    "id": 4,
    "name": "Enterprise",
    "identifier": "enterprise",
    "days_left": 64,
    "start_date": "2025-07-24T09:26:14.868326Z",
    "end_date": "2025-12-23T09:26:14.868326Z",
    "remaining_resources": {
      "available_audio_minutes": 4994,
      "available_call_minutes": 9655,
      "available_text_tokens": 600000,
      "available_image_tokens": 98
    },
    "usage": {
      "used_audio_minutes": 5006,
      "used_call_minutes": 0,
      "used_text_tokens": 0,
      "used_image_tokens": 9902
    },
    "transcription_enabled": true,
    "image_generation_enabled": true,
    "calls_enabled": true
  },
  "directories": [
    { "id": 70, "name": "Website promotion" }
  ],
  "last_tasks": [
    {
      "directory_id": null,
      "status": "completed",
      "id": "b7a62594-a664-4519-b0de-077b5522e245",
      "created_at": "2025-10-20T08:45:25.670423Z",
      "file_path": "exten-110-060865882-20251020-112158-1760948518.13620249.wav",
      "task_length": 6.4
    },
    {
      "directory_id": null,
      "status": "completed",
      "id": "04a7b144-e43b-4792-affa-65a030c1b6bf",
      "created_at": "2025-10-20T08:45:22.964481Z",
      "file_path": "q-888-060501523-20251020-114310-1760949769.13620656.wav",
      "task_length": 2.0
    }
  ],
  "call_activity_tree": {
    "2025": { "10": { "01": 247, "02": 316 } }
  }
}

Parameter description (response)

Parameter	Type	Description
message	string	Successful authentication message.
error_code	int	Error code (`0` on success).
token	string (JWT)	Authorization token for private methods.
locale	string	Default language for the user.
user_id	int	User identifier.
email	string	User email.
tariff	object	Active plan information (see fields below).
tariff.id	int	Plan identifier.
tariff.name	string	Plan name.
tariff.identifier	string	Unique plan identifier.
tariff.days_left	int	Number of days remaining until plan expiration.
tariff.start_date	datetime	Plan start date (ISO 8601).
tariff.end_date	datetime	Plan end date (ISO 8601).
tariff.remaining_resources.available_audio_minutes	int	Available audio minutes.
tariff.remaining_resources.available_call_minutes	int	Available call minutes.
tariff.remaining_resources.available_text_tokens	int	Available text tokens.
tariff.remaining_resources.available_image_tokens	int	Available image tokens.
tariff.usage.used_audio_minutes	int	Used audio minutes.
tariff.usage.used_call_minutes	int	Used call minutes.
tariff.usage.used_text_tokens	int	Used text tokens.
tariff.usage.used_image_tokens	int	Used image tokens.
tariff.transcription_enabled	bool	Whether transcription is enabled.
tariff.image_generation_enabled	bool	Whether image generation is enabled.
tariff.calls_enabled	bool	Whether call processing is enabled.
directories	array	User directories.
directories[].id	int	Directory identifier.
directories[].name	string	Directory name.
last_tasks	array	Latest user tasks (up to 5).
last_tasks[].directory_id	int \	null
last_tasks[].status	string	Task status.
last_tasks[].id	string (uuid)	Public task code (`code_uuid`).
last_tasks[].created_at	datetime	Creation time (ISO 8601, Z).
last_tasks[].file_path	string	File name (for audio/calls).
last_tasks[].task_length	number	Duration in minutes.
call_activity_tree	object	Call activity tree by years/months/days.

2) Account (Balance)

Get current balance and active plan details

GET /user/tariff

Returns information about the user's active plan, remaining resources, and usage. Requires JWT authorization.

curl -X GET "https://<host>/user/tariff" \
  -H "Authorization: Bearer <JWT>" \
  -H "Accept-Language: en"

Parameter description (request)

Parameter	Type	Required	Description
—	—	—	No parameters in URL/body. The `Authorization: Bearer <JWT>` header is required.

Example response (200)

{
  "success": true,
  "errorcode": 0,
  "tariff": {
    "id": 4,
    "name": "Enterprise",
    "identifier": "enterprise",
    "days_left": 64,
    "text_tokens": 600000,
    "image_tokens": 98,
    "limits": {
      "audio_minutes": 10000,
      "call_minutes": 9655,
      "text_tokens": 600000,
      "image_tokens": 10000,
      "report_count": 25,
      "video_minutes": 3000,
      "chat_count": 500
    },
    "remaining_resources": {
      "available_audio_minutes": 4994,
      "available_call_minutes": 9655,
      "available_text_tokens": 600000,
      "available_image_tokens": 98,
      "available_report_count": 24,
      "available_video_minutes": 2980,
      "available_chat_count": 500
    },
    "usage": {
      "used_audio_minutes": 5006,
      "used_call_minutes": 0,
      "used_text_tokens": 0,
      "used_image_tokens": 9902,
      "used_report_count": 1,
      "used_video_minutes": 20,
      "used_chat_count": 0
    },
    "transcription_enabled": true,
    "image_generation_enabled": true,
    "calls_enabled": true,
    "start_date": "2025-07-24T09:26:14.868326Z",
    "end_date": "2025-12-23T09:26:14.868326Z",
    "price": {
      "currency": "USD",
      "value": 99.9
    }
  }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
errorcode	int	Error code (`0` on success).
tariff	object	Active plan information (see fields below).
tariff.id	int	Plan identifier.
tariff.name	string	Plan name.
tariff.identifier	string	Unique plan identifier.
tariff.days_left	int	Full days until plan expiration (rounded up, minimum 0).
tariff.text_tokens	int	Legacy: duplicates `remaining_resources.available_text_tokens` for backward compatibility.
tariff.image_tokens	int	Legacy: duplicates `remaining_resources.available_image_tokens` for backward compatibility.
tariff.limits	object	Plan limits.
tariff.limits.audio_minutes	int	Max audio minutes per plan.
tariff.limits.call_minutes	int	Max call minutes per plan.
tariff.limits.text_tokens	int	Max text tokens.
tariff.limits.image_tokens	int	Max image generation tokens.
tariff.limits.report_count	int	Report limit (business reports).
tariff.limits.video_minutes	int	Video minutes limit.
tariff.limits.chat_count	int	Chat analysis interaction limit.
tariff.remaining_resources	object	Current remaining resources.
tariff.remaining_resources.available_audio_minutes	int	Available audio minutes.
tariff.remaining_resources.available_call_minutes	int	Available call minutes.
tariff.remaining_resources.available_text_tokens	int	Available text tokens.
tariff.remaining_resources.available_image_tokens	int	Available image generation tokens.
tariff.remaining_resources.available_report_count	int	Available reports.
tariff.remaining_resources.available_video_minutes	int	Available video minutes.
tariff.remaining_resources.available_chat_count	int	Available chat analyses.
tariff.usage	object	Actual usage (calculated as `limit - remaining`, not below 0).
tariff.usage.used_audio_minutes	int	Used audio minutes.
tariff.usage.used_call_minutes	int	Used call minutes.
tariff.usage.used_text_tokens	int	Used text tokens.
tariff.usage.used_image_tokens	int	Used image generation tokens.
tariff.usage.used_report_count	int	Used reports.
tariff.usage.used_video_minutes	int	Used video minutes.
tariff.usage.used_chat_count	int	Used chat analyses.
tariff.transcription_enabled	bool	Whether transcription is enabled.
tariff.image_generation_enabled	bool	Whether image generation is enabled.
tariff.calls_enabled	bool	Whether call processing is enabled.
tariff.start_date	datetime	Plan start date (ISO 8601, UTC, `Z`).
tariff.end_date	datetime	Plan end date (ISO 8601, UTC, `Z`).
tariff.price	object	(Optional) Plan price for the region from `Accept-Language`.
tariff.price.currency	string	Currency.
tariff.price.value	number	Price.

3) Tasks

Create a call processing task (file)

POST /addtaskcall — multipart/form-data

Creates a task to process a call from an uploaded file.

curl -X POST "https://<host>/addtaskcall" \
  -H "Authorization: Bearer <JWT>" \
  -F "file=@/path/to/call.wav" \
  -F "directory_id=123" \
  -F "operator_name=Ivan" \
  -F "client_id=C-42" \
  -F "call_type=inbound" \
  -F "call_date=2025-10-20" \
  -F "call_datetime=2025-10-20T10:00:00+03:00" \
  -F "processing_type=standard"

Parameter description (request)

Parameter	Type	Required	Description
file	file	yes	Call audio file (WAV/MP3/OGG, etc.). Minimum duration ≈ 2 seconds.
directory_id	int	no	Directory ID (`0` is treated as `null`).
operator_name	string	no	Operator name/label (default `global`).
client_id	string	no	Customer identifier.
call_type	string	no	`inbound` \
call_date	date	no	Call date `YYYY-MM-DD`.
call_datetime	datetime	no	Full date/time in ISO 8601 with TZ (e.g., `2025-10-20T10:00:00+03:00`).
processing_type	string	no	Queue mode: `standard` \

Example response (200)

{
  "id": 101,
  "error_code": 0,
  "code": "a1bc2d3e-4f56-7890-abcd-ef1234567890"
}

Parameter description (response)

Parameter	Type	Description
id	int	Internal task identifier.
error_code	int	Error code (`0` on success).
code	string (uuid)	Public task code.

Possible errors (HTTP 200, JSON)

Code	Description
4001	Invalid parameters (including an invalid `directory_id` or `call_datetime` without TZ).
4024	File not provided.
4025	Unsupported file format.
4026	File decoding error.
4044	No active plan.
4050	Not enough plan minutes (calls).
4091	Duplicate file (same original filename already uploaded).
4092	Audio is too short (< 2 sec) or length limit exceeded.
5000	Internal server error.

Create a call processing task by URL

POST /addtaskcallbyurl — JSON

Creates a task to process a call by downloading the audio from a link.

curl -X POST "https://<host>/addtaskcallbyurl" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/rec_001.wav",
    "directory_id": 123,
    "operator_name": "Ivan",
    "client_id": "C-42",
    "call_type": "outbound",
    "call_date": "2025-10-20",
    "call_datetime": "2025-10-20T10:00:00+03:00",
    "processing_type": "analysis"
  }'

Parameter description (request)

Parameter	Type	Required	Description
file_url	string (URL)	yes	Direct link to the audio file.
directory_id	int	no	Directory ID.
operator_name	string	no	Operator name/label (default `global`).
client_id	string	no	Customer identifier.
call_type	string	no	`inbound` \
call_date	date	no	`YYYY-MM-DD`.
call_datetime	datetime	no	ISO 8601 with TZ.
processing_type	string	no	Mode: `analysis` \

Example response (200)

{
  "id": 102,
  "error_code": 0,
  "code": "9360911d-34ce-4e1f-9259-2ba0a1b96ae7"
}

Parameter description (response)

Parameter	Type	Description
id	int	Internal task identifier.
error_code	int	Error code (`0` on success).
code	string (uuid)	Public task code.

Possible errors (HTTP 200, JSON)

Code	Description
4001	Invalid parameters (including `call_datetime` without TZ).
4002	`file_url` not provided.
4024	Failed to download the file by URL.
4044	No active plan.
4050	Not enough plan minutes (calls).
4092	Audio is too short/empty after downloading.
5000	Internal server error.

Create an audio processing task (file)

POST /addtaskaudio — multipart/form-data

Adds a task to process an arbitrary audio file.

curl -X POST "https://<host>/addtaskaudio" \
  -H "Authorization: Bearer <JWT>" \
  -F "file=@/path/to/audio.mp3" \
  -F "directory_id=321" \
  -F "file_lang=00"

Parameter description (request)

Parameter	Type	Required	Description
file	file	yes	Audio file. Minimum duration ≈ 2 seconds.
directory_id	int	no	Directory ID.
file_lang	string	no	Language/locale code (default `00` — auto-detect).

Example response (200)

{
  "id": 103,
  "error_code": 0,
  "code": "a1bc2d3e-4f56-7890-abcd-ef1234567890"
}

Parameter description (response)

Parameter	Type	Description
id	int	Internal task identifier.
error_code	int	Error code (`0` on success).
code	string (uuid)	Public task code.

Possible errors (HTTP 200, JSON)

Code	Description
4024	File not provided.
4025	Unsupported file format.
4026	File decoding error.
4044	No active plan.
4050	Not enough plan minutes (audio).
4092	Audio is too short/too long.
5000	Internal server error.

Create a YouTube processing task

POST /addtaskyoutube — JSON

Adds a task to transcribe audio from a video link (YouTube/VK/TikTok, etc. are supported).

curl -X POST "https://<host>/addtaskyoutube" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "directory_id": 555,
    "file_lang": "00"
  }'

Parameter description (request)

Parameter	Type	Required	Description
file_path	string (URL)	yes	Video link.
directory_id	int	no	Directory ID.
file_lang	string	no	Language/locale code (default `00`).

Example response (200)

{
  "id": 104,
  "error_code": 0,
  "code": "b2cd3e4f-5678-90ab-cdef-0123456789ab",
  "demo": false
}

Parameter description (response)

Parameter	Type	Description
id	int	Internal task identifier.
error_code	int	Error code (`0` on success).
code	string (uuid)	Public task code.
demo	bool	Demo mode flag (usually `false` for the private API).

Possible errors (HTTP 200, JSON)

Code	Description
4017	Invalid/unsupported URL.
4044	No active plan.
5000	Internal server error.

Create a chat analysis task (text)

POST /add_chat_analysis_task — JSON

Accepts text/chunks of a dialog, creates a chat task, and queues it for analysis.

curl -X POST "https://<host>/add_chat_analysis_task" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Dialog with a customer...",
    "chunks": null,
    "operator_name": "Operator 1",
    "call_date": "2025-10-20"
  }'

Parameter description (request)

Parameter	Type	Required	Description
text	string \	null	no
chunks	array \	null	no
operator_name	string	no	Operator name/label.
call_date	date	no	`YYYY-MM-DD` \

Example response (200)

{
  "success": true,
  "error_code": 0,
  "success_message": "Chat analysis task created",
  "task_code": "c0ffee00-1234-5678-aaaa-bbbbbbbbbbbb"
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the task was created successfully.
error_code	int	Error code (`0` on success).
success_message	string	Success message.
task_code	string (uuid)	Public task code.

Create a report task (calls/chats)

POST /user/callreport — JSON

Creates a task to generate a period report for your calls/chats.

curl -X POST "https://<host>/user/callreport" \
  -H "Authorization: Bearer <JWT>" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-10-01",
    "end_date": "2025-10-31",
    "report_type": "standard"
  }'

Parameter description (request)

Parameter	Type	Required	Description
start_date	date \	datetime	yes
end_date	date \	datetime	yes
report_type	string	no	Report type: `standard` (default) \

Example response (200)

{
  "success": true,
  "error_code": 0,
  "success_message": "Report task created",
  "report_task_code": "b7a62594-a664-4519-b0de-077b5522e245",
  "available_report_count": 7
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the task was created successfully.
error_code	int	Error code (`0` on success).
success_message	string	Success message.
report_task_code	string (uuid)	Public report task code (GUID).
available_report_count	int	Remaining report quota (only for `business`).

Possible errors (HTTP 200, JSON)

Code	Description
4023	Unauthorized (missing/invalid JWT).
4060	Dates not provided (`start_date`/`end_date`).
4061	Invalid date format.
4062	`start_date` is later than `end_date`.
4602	No active plan or business report quota exhausted.
5000	Generic internal error.

4) Retrieving results

Get all user tasks with the specified filters

POST /tasks/filter
GET /tasks/filter

Purpose. Flexible task selection across many criteria: basic task fields, full-text search, call analytics filters (only via *_id) and checklist answer filters. Pagination is supported for both methods. Important: date filters apply to Task.call_datetime (UTC).

curl -X POST "https://<host>/tasks/filter" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "task_type": "call",
    "status": "completed",
    "date_from": "2025-10-01",
    "date_to": "2025-10-31",
    "message": "esim setup",
    "operator_name": "Ivanov",
    "call_type": "inbound",
    "tags_any": "eSIM,APN",
    "script_alignment_min": 60,
    "customer_satisfaction_score_min": 7,
    "tone_id": [1,2],
    "resolved_status_id": 5,
    "priority_id": 3,
    "funnel_stage_id": [4,5],
    "risk_signal_id": null,
    "sales_signal_id": null,
    "operator_politeness": [4,5],
    "operator_politeness_min": 3,
    "operator_politeness_max": 5,
    "length_min": 3.5,
    "length_max": 120,
    "checklist_id": 7,
    "answers": ["Yes","Partially"],
    "page": 1,
    "per_page": 12
  }'

curl -G "https://<host>/tasks/filter" \
  -H "Authorization: Bearer <JWT>" \
  -H "Accept-Language: en" \
  --data-urlencode "task_type=call" \
  --data-urlencode "status=completed" \
  --data-urlencode "date_from=2025-10-01" \
  --data-urlencode "date_to=2025-10-31" \
  --data-urlencode "message=esim" \
  --data-urlencode "operator_name=Ivanov" \
  --data-urlencode "call_type=inbound" \
  --data-urlencode "tags_any=eSIM,APN" \
  --data-urlencode "tone_id=1,2" \
  --data-urlencode "priority_id=3" \
  --data-urlencode "resolved_status_id=5" \
  --data-urlencode "operator_politeness=4,5" \
  --data-urlencode "operator_politeness_min=3" \
  --data-urlencode "operator_politeness_max=5" \
  --data-urlencode "length_min=3.5" \
  --data-urlencode "length_max=120" \
  --data-urlencode "checklist_id=7" \
  --data-urlencode "answers=Yes" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=12"

Parameter description (request)

Parameter	Type	Required	Description
task_code	string (UUID \	legacy)	no
task_id	int	no	Internal task identifier.
date_from	date \	datetime	no
date_to	date \	datetime	no
task_type	string	no	Task type: `call`, `chat`, `email`, `audio`, `youtubenew`, `callreport`.
status	string	no	Status: `pending`, `processing`, `audio_completed`, `completed`, `completed2`, `error`.
call_type	string	no	Call type: `inbound` \
operator_name	string	no	Substring match on operator name (`ILIKE`).
message	string	no	Full-text search across: `CallsAnalysis.summary`, `TaskResult.original_text`, `TaskResult.normalized_text`.
tone_id	int \	int[]	no
resolved_status_id	int \	int[]	no
priority_id	int \	int[]	no
funnel_stage_id	int \	int[]	no
risk_signal_id	int \	int[]	no
sales_signal_id	int \	int[]	no
script_alignment_min	number	no	Min script alignment (0–100).
script_alignment_max	number	no	Max script alignment (0–100).
customer_satisfaction_score_min	int	no	Min CSAT (0–10).
customer_satisfaction_score_max	int	no	Max CSAT (0–10).
operator_politeness	int \	int[]	no
operator_politeness_min	int	no	Lower bound of rating (1..5).
operator_politeness_max	int	no	Upper bound of rating (1..5).
tags_any	string \	string[]	no
tags_all	string \	string[]	no
length_min	number	no	Min task duration (minutes) by `Task.task_length`.
length_max	number	no	Max task duration (minutes) by `Task.task_length`.
checklist_id	int	no	Filter by a checklist question.
answers	string \	string[]	no
page	int	no	Page number (default 1).
per_page	int	no	Page size (default 10).
Accept-Language	header	no	Localization language (`ru`, `en`, etc.).

Example response (200)

{
  "tasks": [
    {
      "id": 12345,
      "type": "call",
      "status": "completed",
      "file_name": "rec_2025-10-20_0845.wav",
      "created_at": "2025-10-20T08:45:14+00:00",
      "updated_at": "2025-10-20T08:47:10+00:00",

      "operator_name": "Ivanov",
      "call_time": "2025-10-20T08:45:00+00:00",
      "call_type": "inbound",
      "call_date": "2025-10-20",

      "error_message": null,
      "directory_id": 123,
      "task_length": 64.2,
      "task_code": "9289bd97-ac8c-41b3-bce8-fbcd86f1da7c",
      "report_type": null,
      "customer_satisfaction_score": 8
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 12,
    "total_tasks": 34,
    "total_pages": 3
  }
}

Parameter description (response)

Parameter	Type	Description
tasks	array	List of found tasks.
tasks[].id	int	Task identifier.
tasks[].type	string	Task type.
tasks[].status	string	Processing status.
tasks[].file_name	string \	null
tasks[].created_at	datetime \	null
tasks[].updated_at	datetime \	null
tasks[].operator_name	string \	null
tasks[].call_time	datetime \	null
tasks[].call_type	string \	null
tasks[].call_date	date \	null
tasks[].error_message	string \	null
tasks[].directory_id	int \	null
tasks[].task_length	number	Duration in minutes (for `chat`/`email` returns `0`).
tasks[].task_code	string (uuid)	Public task code.
tasks[].report_type	string \	null
tasks[].customer_satisfaction_score	int \	null
pagination	object	Pagination information.
pagination.current_page	int	Current page.
pagination.per_page	int	Page size.
pagination.total_tasks	int	Total tasks found.
pagination.total_pages	int	Total pages.

Get detailed task data

GET /gettask

Purpose. Return the core task information: statuses, files, dates, duration, short raw/normalized text (if any), bindings and errors.

curl -G "https://<host>/gettask" \
  -H "Authorization: Bearer <JWT>" \
  --data-urlencode "task_code=9360911d-34ce-4e1f-9259-2ba0a1b96ae7"

Parameter description (request)

Parameter	Type	Required	Description
task_code	uuid-string	yes	Public task GUID.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "id": 112233,
  "type": "call",
  "status": "completed",
  "file_name": "rec_2025-10-01_0750.wav",
  "created_at": "2025-10-01T07:50:00+00:00",
  "updated_at": "2025-10-01T08:02:31+00:00",
  "call_date": "2025-10-01",
  "error_message": null,
  "directory_id": 77,
  "report_type": null,
  "task_code": "9360911d-34ce-4e1f-9259-2ba0a1b96ae7",
  "task_length": 16.62,
  "task_result": {
    "blog_post": null,
    "image_prompt": null,
    "normalized_text": null,
    "original_text": "Operator: Hello, Smile Telecom, my name is Olga..."
  }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the response is successful.
error_code	int	Error code (`0` on success).
id	int	Internal task identifier.
type	string	`call` \
status	string	`pending` \
file_name	string \	null
created_at	datetime	Creation time (ISO 8601, with TZ).
updated_at	datetime	Update time (ISO 8601, with TZ).
call_date	date \	null
error_message	string \	null
directory_id	int \	null
report_type	string \	null
task_code	uuid-string	Public task GUID.
task_length	number	Duration/size of the source data.
task_result	object \	null

Notes

In case of a business error, error_code/error_message are set; other fields may be null/empty (HTTP 200).
task_result.* fields are present only if the corresponding processing modes were enabled/completed.

Get call analysis for a task

GET /api/calls_analysis_v2/{task_code}

Purpose. Return the call analytics structure for a call/task: narrative, intents, reasons, signals, recommendations, scores (CSAT/emotions/politeness), tags, checklists, etc.

curl -X GET "https://<host>/api/calls_analysis_v2/9360911d-34ce-4e1f-9259-2ba0a1b96ae7" \
  -H "Authorization: Bearer <JWT>" \
  -H "Accept: application/json" \
  -H "Accept-Language: en"

Parameter description (request)

Parameter	Type	Required	Description
task_code	path-uuid	yes	Task GUID in the URL path.
Accept-Language	header	no	Localization of human-readable texts (if available).

Example response (200)

{
  "success": true,
  "error_code": 0,
  "task_code": "9360911d-34ce-4e1f-9259-2ba0a1b96ae7",
  "call_datetime": "2025-10-01T07:50:00+00:00",
  "call_type": "inbound",
  "duration_sec": 996,
  "transcript": {
    "language": "en",
    "turns": 128
  },
  "analysis": {
    "summary": "The customer wants to enable eSIM and a static IP for remote access; the operator explained the steps, confirmed the plan, and promised to send an SMS with instructions.",
    "sentiment": "positive",
    "scores": {
      "csat": 9,
      "politeness": 0.95,
      "empathy": 0.86
    },
    "actions": [
      "Send an SMS with eSIM activation instructions",
      "Provide APN parameters for a stable connection",
      "Check whether there are outages in the customer's area"
    ],
    "tags": ["eSIM","APN","Static IP","Remote access"],
    "analysis_notes": {
      "decision_driver": "eSIM activation + static IP",
      "emotional_dynamics": "calm, grateful",
      "funnel_stage": "qualification",
      "intention": "get stable remote access",
      "key_obstacles": "no eSIM activation in the personal account; possible network outages",
      "next_action": "the customer is waiting for SMS confirmation and instructions",
      "operator_commitments": "send SMS, provide APN, check outages",
      "product_or_service": "mobile service, eSIM, static IPv4",
      "reason_for_contact": "eSIM activation, issues with VoLTE",
      "risk_signals": "none",
      "root_cause": "technical",
      "sales_signals": "upsell"
    }
  },
  "call_checklists": [
    {
      "checklist_id": 7,
      "title": "Greeting script",
      "score": 0.9,
      "answers": [
        {"question_id": 1, "title": "Operator introduced themselves", "value": true},
        {"question_id": 2, "title": "Verified customer details", "value": true}
      ]
    }
  ],
  "category_ids": [101, 202],
  "customer_satisfaction_score": 9
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the response is successful.
error_code	int	Error code (`0` on success).
task_code	uuid-string	Task GUID.
call_datetime	datetime	Call time (ISO 8601, with TZ).
call_type	string	`inbound` \
duration_sec	int	Call duration in seconds.
transcript	object	Short transcript statistics.
transcript.language	string	Transcript language (BCP-47).
transcript.turns	int	Number of dialogue turns.
analysis	object	Final call analytics.
analysis.summary	string	Short conversation summary.
analysis.sentiment	string	Overall sentiment (`positive`/`neutral`/`negative`).
analysis.scores	object	Normalized metrics (for example, CSAT).
analysis.actions	string[]	Recommended next steps.
analysis.tags	string[]	Call tags.
analysis.analysis_notes	object	Detailed notes (signals, intent, etc.).
call_checklists	array	Checklist results for the call.
category_ids	int[]	Categories (if classification was performed).
customer_satisfaction_score	int \	null

Notes

The analysis block structure may expand without changing the API version (new keys may be added).
If some subsystems are absent (categories, checklists), the corresponding fields may be empty/null.
In case of a business error, the API returns success: false and error_code/error_message (HTTP 200).

5) Checklists

API for managing checklist questions and working with task answers.

Get active checklist questions

GET /checklist
GET /checklist/{user_id} — optional, for an administrator

curl -X GET "https://<host>/checklist" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
user_id	path-int	no	User identifier (variant `GET /checklist/{user_id}`). Without the parameter — active checklists of the current user.
Authorization	header	yes	`Bearer <JWT>` token.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "data": [
    { "id": 1, "question": "Did the operator introduce themselves to the customer?", "is_active": true },
    { "id": 2, "question": "Did the operator clarify the purpose of the call?", "is_active": true }
  ]
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
data	array	List of active checklist questions.
data[].id	int	Question identifier.
data[].question	string	Question text.
data[].is_active	bool	Whether the question is active.

Pagination

Not used for this method (all active questions are returned).

Create a checklist question

POST /checklist

Creates a new checklist question for the current user.

curl -X POST "https://<host>/checklist" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Did the operator introduce themselves?" }'

Parameter description (request)

Parameter	Type	Required	Description
question	string	yes	Checklist question text.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "message": "Checklist question created",
  "data": { "id": 101, "question": "Did the operator introduce themselves?", "is_active": true }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
message	string	Service message confirming creation.
data	object	Created checklist question.
data.id	int	Question identifier.
data.question	string	Question text.
data.is_active	bool	Active flag (default `true`).

Edit a checklist question

POST /checklist/{checklist_id}

Edits the question text if there are no conflicting dependencies yet (business constraints may apply).

curl -X POST "https://<host>/checklist/101" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Did the operator clearly introduce themselves?" }'

Parameter description (request)

Parameter	Type	Required	Description
checklist_id	path-int	yes	Question identifier in the URL.
question	string	yes	New question text.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "message": "Checklist question updated",
  "data": { "id": 101, "question": "Did the operator clearly introduce themselves?", "is_active": true }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
message	string	Service message confirming update.
data	object	Updated checklist question.
data.id	int	Question identifier.
data.question	string	Question text.
data.is_active	bool	Active flag.

Delete (hide) a checklist question

POST /checklist/delete/{checklist_id}

Deletes/hides a checklist question.

curl -X POST "https://<host>/checklist/delete/101" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
checklist_id	path-int	yes	Question identifier, passed in the URL.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "message": "Checklist question deleted",
  "id": 101
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
message	string	Service message confirming deletion/hiding.
id	int	Deleted question identifier.

Get checklist answers for a task

GET /checklist/answer/{task_id}

Returns answers to checklist questions for a specific task.

curl -X GET "https://<host>/checklist/answer/12345" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
task_id	path-int	yes	Task identifier.
Authorization	header	yes	`Bearer <JWT>` token.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "data": [
    { "checklist_id": 1, "question": "Did the operator introduce themselves?", "answer": "Yes" },
    { "checklist_id": 2, "question": "Did the operator clarify the purpose of the call?", "answer": "No" }
  ]
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
data	array	List of answers for the task.
data[].checklist_id	int	Checklist question identifier.
data[].question	string	Question text (for client convenience).
data[].answer	string	User/operator answer.

Field construction rules

question — a non-empty string. A concise statement form is recommended.
answer — a string. “Yes”/“No” are acceptable, or any free text based on business logic.
is_active — boolean; inactive questions are not returned by GET /checklist.
task_id — internal task identifier (see “Tasks” section).
All date/time values (if present) are ISO 8601 with timezone.

Example elements

Checklist question: json { "id": 7, "question": "Did they state the plan conditions?", "is_active": true }

Task answer: json { "checklist_id": 7, "question": "Did they state the plan conditions?", "answer": "Yes" }

Notes

Re-sending an answer for the same checklist_id and the same task_id overwrites the previous answer.
Unknown/hidden questions are ignored during bulk answer submission.
In case of business errors, the API returns success: false with error_code and error_message while still responding with HTTP 200.

6) Directories

Section for managing user directories where tasks are stored.

Get the list of directories

GET /user/directories

Returns all directories created by the user.

curl -X GET "https://<host>/user/directories" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
—	—	—	No parameters in URL/body. The `Authorization: Bearer <JWT>` header is required.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "directories": [
    { "id": 70, "name": "Website promotion" },
    { "id": 71, "name": "Sales department" }
  ]
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
directories	array	List of user directories.
directories[].id	int	Directory identifier.
directories[].name	string	Directory name.

Create a directory

POST /user/directories

Creates a new directory for organizing user tasks.

curl -X POST "https://<host>/user/directories" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New directory" }'

Parameter description (request)

Parameter	Type	Required	Description
name	string	yes	Name of the new directory.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "directory": { "id": 123, "name": "New directory" }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
directory	object	The created directory.
directory.id	int	Directory identifier.
directory.name	string	Directory name.

Delete a directory

DELETE /user/directories/delete/{directory_id}

Deletes the specified directory. Note: the path contains exactly one directory_id at the end.

curl -X DELETE "https://<host>/user/directories/delete/123" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
directory_id	path-int	yes	Identifier of the directory to delete (passed in the URL).

Example response (200)

{
  "error_code": 0,
  "message": "Directory deleted successfully"
}

Parameter description (response)

Parameter	Type	Description
error_code	int	Error code (`0` on success).
message	string	Successful deletion message.

7) Call categories

Directory of call categories. Allows you to build a hierarchical taxonomy of interaction topics (parent → child).

Category list

POST /user/call_categories/list

Returns the user's categories with search and pagination support.

curl -X POST "https://<host>/user/call_categories/list" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "tech",
    "parent_id": null,
    "page": 1,
    "per_page": 10
  }'

Parameter description (request)

Parameter	Type	Required	Description
q	string	no	Search by partial match of `name`/`description`.
parent_id	int \	null	no
page	int	no	Page number (default 1).
per_page	int	no	Page size (default 20).
Authorization	header	yes	`Bearer <JWT>` token.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "items": [
    {
      "id": 1,
      "name": "Sales",
      "description": "Sales calls",
      "parent_id": null,
      "children_count": 2,
      "created_at": "2025-10-20T12:35:41+00:00",
      "updated_at": "2025-10-22T09:10:00+00:00"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 10
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
items	array	Category list on the current page.
items[].id	int	Category identifier.
items[].name	string	Category name.
items[].description	string \	null
items[].parent_id	int \	null
items[].children_count	int	Number of child categories.
items[].created_at	datetime	Creation time (ISO 8601).
items[].updated_at	datetime	Update time (ISO 8601).
total	int	Total records matching the filter.
page	int	Current page number.
per_page	int	Page size.

Create a category

POST /user/call_categories/create

Creates a new user category.

curl -X POST "https://<host>/user/call_categories/create" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Tech support", "description": "Technical inquiries", "parent_id": null }'

Parameter description (request)

Parameter	Type	Required	Description
name	string	yes	Category name.
description	string	no	Description.
parent_id	int \	null	no

Example response (200)

{
  "success": true,
  "error_code": 0,
  "success_message": "Saved successfully",
  "data": {
    "id": 12,
    "name": "Tech support",
    "description": "Technical inquiries",
    "parent_id": null,
    "created_at": "2025-10-20T12:35:41+00:00",
    "updated_at": "2025-10-20T12:35:41+00:00"
  }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
success_message	string	Service message confirming save.
data	object	Created category (see fields below).
data.id	int	Identifier.
data.name	string	Name.
data.description	string \	null
data.parent_id	int \	null
data.created_at	datetime	Creation time (ISO 8601).
data.updated_at	datetime	Update time (ISO 8601).

Edit a category

POST /user/call_categories/edit/{id}

Edits category properties. The ID is taken from the URL; you can also pass category_id in the request body (if present, it takes precedence).

curl -X POST "https://<host>/user/call_categories/edit/12" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Tech support (L2)", "description": "Complex technical issues", "parent_id": 2 }'

Parameter description (request)

Parameter	Type	Required	Description
id	path-int	yes	Category identifier in the URL.
category_id	int	no	Identifier in the body (overrides `id` from the URL).
name	string	no	New name.
description	string	no	New description.
parent_id	int \	null	no

Example response (200)

{
  "success": true,
  "error_code": 0,
  "success_message": "Saved successfully",
  "data": {
    "id": 12,
    "name": "Tech support (L2)",
    "description": "Complex technical issues",
    "parent_id": 2,
    "created_at": "2025-10-20T12:35:41+00:00",
    "updated_at": "2025-10-22T09:10:00+00:00"
  }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
success_message	string	Service message confirming save.
data	object	Updated category (fields same as in “Create a category”).

Delete a category

POST /user/call_categories/delete/{id}

Deletes a user category.

curl -X POST "https://<host>/user/call_categories/delete/12" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
id	path-int	yes	Category identifier.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "message": "Deleted successfully"
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
message	string	Service message confirming deletion.

Error codes (HTTP 200) {#kody-oshibok-http-200}

Code	Description
4023	Unauthorized / user not found
4045	Cannot delete a category that has child records
4059	Category not found (or not accessible to the user)
5000	Internal server error

8) Task search filters

API for saving, listing, and deleting saved task search filters.

General: all methods require JWT authorization. Errors are returned with HTTP 200 and the body { "success": false, "error_code": <int>, "error_message": "<string>" }.

Save filter configuration

POST /tasks/filters/save

Creates a new filter or updates an existing one by name (for the current user). The criteria field must be passed in the same format as the /tasks/filter endpoint parameters.

curl -X POST "https://<host>/tasks/filters/save" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Critical calls — October",
    "criteria": {
      "task_type": "call",
      "status": "completed",
      "date_from": "2025-10-01",
      "date_to": "2025-10-31",
      "message": "complaint",
      "call_type": "inbound",
      "operator_name": "Ivanov",
      "tone_id": [1,2],
      "resolved_status_id": 5,
      "priority_id": 3,
      "funnel_stage_id": [4,5],
      "risk_signal_id": null,
      "sales_signal_id": null,
      "script_alignment_min": 60,
      "customer_satisfaction_score_min": 8,
      "operator_politeness": [4,5],
      "operator_politeness_min": 3,
      "operator_politeness_max": 5,
      "tags_any": "eSIM,APN",
      "length_min": 2,
      "length_max": 90,
      "checklist_id": 7,
      "answers": ["Yes","Partially"],
      "page": 1,
      "per_page": 12
    }
  }'

Parameter description (request)

Parameter	Type	Required	Description
name	string	yes	Filter name. If it already exists, it will be updated.
criteria	object (JSON)	yes	Keys correspond to `/tasks/filter`: `task_type`, `status`, `date_from`, `date_to`, `message`, `call_type`, `operator_name`, `tone_id`, `resolved_status_id`, `priority_id`, `funnel_stage_id`, `risk_signal_id`, `sales_signal_id`, `script_alignment_min/max`, `customer_satisfaction_score_min/max`, `operator_politeness` (list of values 1..5), `operator_politeness_min/max`, `tags_any`, `tags_all`, `length_min/max`, `checklist_id`, `answers`, `page`, `per_page`.

Example successful response (200)

{ "success": true, "message": "Filter created or updated" }

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
message	string	Service message describing the operation.

Possible errors (HTTP 200, JSON)

Code	Message (example)	Description
4045	Required fields are missing	Required fields `name` and/or `criteria` were not provided.
5000	Internal server error	Internal server error.

List saved filters

GET /tasks/filters/list

Returns all saved filters for the current user.

curl -X GET "https://<host>/tasks/filters/list" \
  -H "Authorization: Bearer <JWT>"

Example response (200)

{
  "success": true,
  "count": 2,
  "filters": [
    {
      "id": 42,
      "name": "Critical calls — October",
      "criteria": {
        "task_type": "call",
        "priority_id": 3,
        "date_from": "2025-10-01",
        "date_to": "2025-10-31"
      },
      "created_at": "2025-10-31T12:00:00"
    },
    {
      "id": 43,
      "name": "Chats with low CSAT",
      "criteria": {
        "task_type": "chat",
        "customer_satisfaction_score_max": 4
      },
      "created_at": "2025-11-01T09:15:00"
    }
  ]
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
count	int	Number of filters found.
filters	array	Saved filters.
filters[].id	int	Filter identifier.
filters[].name	string	Filter name.
filters[].criteria	object	JSON criteria (see `/tasks/filter`).
filters[].created_at	string (ISO)	Creation date/time.

Delete a saved filter

POST /tasks/filters/delete/{filter_id}

Deletes a saved filter by its identifier.

curl -X POST "https://<host>/tasks/filters/delete/42" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
filter_id	path-int	yes	Filter identifier (in the URL).

Example response (200)

{ "success": true, "message": "Filter deleted" }

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
message	string	Service message describing the operation.

Possible errors (HTTP 200, JSON)

Code	Message (example)	Description
4066	Filter not found	No filter with such `filter_id` was found for the current user.
5000	Internal server error	Internal server error.

Notes

The criteria field is arbitrary JSON with criteria for the task filtering endpoint (see “Get all user tasks with specified filters”).
All responses use HTTP 200. Success is determined by the success field.

9) Call check scripts

API for managing call check scripts (create, edit, delete, retrieve).

Get the list of scripts

POST /user/call_check_scripts/list

Returns the list of user scripts with filtering and pagination.

curl -X POST "https://<host>/user/call_check_scripts/list" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "welcome",
    "only_active": true,
    "page": 1,
    "per_page": 10
  }'

Parameter description (request)

Parameter	Type	Required	Description
q	string	no	Search by partial match of `identifier`/`title`.
only_active	bool	no	Return only active ones (`true`/`1`/`yes`).
page	int	no	Page number (default `1`).
per_page	int	no	Page size (default `20`).
Authorization	header	yes	`Bearer <JWT>` token.

Example response (200)

{
  "success": true,
  "error_code": 0,
  "total": 2,
  "page": 1,
  "per_page": 10,
  "items": [
    {
      "id": 11,
      "identifier": "welcome_v1",
      "title": "Customer greeting",
      "description": "Greeting and data verification script",
      "is_active": true,
      "version": 1,
      "script_body": "Hello! My name is ...",
      "created_at": "2025-10-20T12:35:41Z",
      "updated_at": "2025-10-22T09:10:00Z"
    }
  ]
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
total	int	Total records.
page	int	Current page number.
per_page	int	Page size.
items	array	Script list.
items[].id	int	Script identifier.
items[].identifier	string	Script identifier unique within the user.
items[].title	string	Script title.
items[].description	string \	null
items[].is_active	bool	Active flag.
items[].version	int	Script version.
items[].script_body	string	Script text (plain text).
items[].created_at	datetime	Creation time (ISO 8601).
items[].updated_at	datetime	Update time (ISO 8601).

Create a script

POST /user/call_check_scripts/create

Creates a new call check script.

curl -X POST "https://<host>/user/call_check_scripts/create" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "welcome_v1",
    "title": "Customer greeting",
    "description": "Greeting and data verification script",
    "is_active": true,
    "version": 1,
    "script_body": "Hello! My name is ..."
  }'

Parameter description (request)

Parameter	Type	Required	Description
identifier	string	yes	Unique script identifier (within the user).
title	string	yes	Script title (non-empty string).
description	string	no	Script description.
is_active	bool	no	Active flag (default `true`).
version	int	no	Version (default `1`).
script_body	string	yes	Script text (non-empty plain text).

Example response (200)

{
  "success": true,
  "error_code": 0,
  "success_message": "Saved successfully",
  "data": {
    "id": 11,
    "identifier": "welcome_v1",
    "title": "Customer greeting",
    "description": "Greeting and data verification script",
    "is_active": true,
    "version": 1,
    "script_body": "Hello! My name is ...",
    "created_at": "2025-10-20T12:35:41Z",
    "updated_at": "2025-10-20T12:35:41Z"
  }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
success_message	string	Service message confirming save.
data	object	Created script (fields same as in the list item).

Edit a script

POST /user/call_check_scripts/edit/{script_id}

Updates script properties. script_id is taken from the URL; if script_id is present in the request body, it takes precedence.

curl -X POST "https://<host>/user/call_check_scripts/edit/11" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "script_id": 11,
    "identifier": "welcome_v2",
    "title": "Customer greeting (extended)",
    "description": "Added verification block",
    "is_active": true,
    "version": 2,
    "script_body": "Hello! My name is ..., let's verify your details ..."
  }'

Parameter description (request)

Parameter	Type	Required	Description
script_id	path-int \	int	yes
identifier	string	no	New identifier (non-empty, unique).
title	string	no	New title (non-empty).
description	string	no	New description.
is_active	bool	no	New active flag.
version	int	no	New version (integer).
script_body	string	no	New script text (non-empty plain text).

Example response (200)

{
  "success": true,
  "error_code": 0,
  "success_message": "Saved successfully",
  "data": {
    "id": 11,
    "identifier": "welcome_v2",
    "title": "Customer greeting (extended)",
    "description": "Added verification block",
    "is_active": true,
    "version": 2,
    "script_body": "Hello! My name is ..., let's verify your details ...",
    "created_at": "2025-10-20T12:35:41Z",
    "updated_at": "2025-10-22T09:10:00Z"
  }
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
success_message	string	Service message confirming save.
data	object	Updated script (fields same as in list item).

Delete a script

POST /user/call_check_scripts/delete/{script_id}

Deletes a script. script_id is taken from the URL; if script_id is present in the request body, it takes precedence.

curl -X POST "https://<host>/user/call_check_scripts/delete/11" \
  -H "Authorization: Bearer <JWT>"

Parameter description (request)

Parameter	Type	Required	Description
script_id	path-int \	int	yes

Example response (200)

{
  "success": true,
  "error_code": 0,
  "message": "Deleted successfully"
}

Parameter description (response)

Parameter	Type	Description
success	bool	Whether the request completed successfully.
error_code	int	Error code (`0` on success).
message	string	Service message confirming deletion.

10) Downloading report files

This section contains methods for downloading generated report and export files.
Important: /get_file requires JWT authorization; /user/callreport/file does not require JWT — access is by task_code.

Period interaction report (callreport): PDF/HTML

GET /user/callreport/file?task_code=<GUID>&filename=<name>

Purpose. Download a generated report file created by a callreport type task. Authorization is performed only by the task GUID (task_code).

# PDF (no JWT)
curl -G "https://<host>/user/callreport/file" \
  --data-urlencode "task_code=b7a62594-a664-4519-b0de-077b5522e245" \
  --data-urlencode "filename=report_78157.pdf"

# HTML (no JWT)
curl -G "https://<host>/user/callreport/file" \
  --data-urlencode "task_code=b7a62594-a664-4519-b0de-077b5522e245" \
  --data-urlencode "filename=report_78157.html"

Parameter description (request)

Parameter	Type	Required	Description
task_code	string	yes	Public task GUID (`Task.code_uuid`) or its short code.
filename	string	yes	File name stored on the server (e.g., `report_78157.pdf`).

Example response (success)

Status: 200 OK
Headers: Content-Type: application/pdf or text/html; Content-Disposition: attachment; filename="<filename>"
Body: binary file contents.

Errors (HTTP 200, JSON)

Code	Message (short)
4001	`task_code and filename are required`
4002	`Invalid filename`
4003	`Invalid path`
4041	`Task not found`
4044	`User id not found for task`
4043	`File missing on disk`
5001	Internal handler error
5000	Generic internal error

DOCX report for a call

GET /get_file?file_type=docx_call&task_code=<GUID>

Purpose. Generate and download a DOCX report for a call task (structure: raw text, header, metadata, analytics, issues, checklist).

curl -G "https://<host>/get_file" \
  -H "Authorization: Bearer <JWT>" \
  --data-urlencode "file_type=docx_call" \
  --data-urlencode "task_code=b7a62594-a664-4519-b0de-077b5522e245"

Parameter description (request)

Parameter	Type	Required	Description
file_type	string	yes	Always `docx_call`.
task_code	string	yes	Public GUID of the user task.

Example response (success)

Status: 200 OK
Headers: Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document; Content-Disposition: attachment; filename="call_report_task<ID>.docx"
Body: binary DOCX contents.

Errors (HTTP 200, JSON)

Code	Message (short)
4023	Unauthorized (missing/invalid JWT)
4045	Missing `task_code`
4021	Task not found for the user
4056	Invalid task type (call expected)
4057	No analysis/checklist data
5002	DB error
5000	Generic internal error

TXT report for a call

GET /get_file?file_type=txt_call&task_code=<GUID>

Purpose. Generate and download a TXT report for a call task (core analytics fields and checklists in text form).

curl -G "https://<host>/get_file" \
  -H "Authorization: Bearer <JWT>" \
  --data-urlencode "file_type=txt_call" \
  --data-urlencode "task_code=b7a62594-a664-4519-b0de-077b5522e245"

Parameter description (request)

Parameter	Type	Required	Description
file_type	string	yes	Always `txt_call`.
task_code	string	yes	Public GUID of the user task.

Example response (success)

Status: 200 OK
Headers: Content-Type: text/plain; charset=utf-8; Content-Disposition: attachment; filename="call_report_task<ID>.txt"
Body: text file.

Errors (HTTP 200, JSON)

Code	Message (short)
4023	Unauthorized (missing/invalid JWT)
4045	Missing `task_code`
4021	Task not found for the user
4056	Invalid task type (call expected)
4057	No analysis/checklist data
5002	DB error
5000	Generic internal error

DOCX report for a YouTube task

GET /get_file?file_type=docx_youtube&task_code=<GUID>

Purpose. Generate and download a DOCX report for a YouTube task (raw/normalized text, summary, short post, blog post).

curl -G "https://<host>/get_file" \
  -H "Authorization: Bearer <JWT>" \
  --data-urlencode "file_type=docx_youtube" \
  --data-urlencode "task_code=b7a62594-a664-4519-b0de-077b5522e245"

Parameter description (request)

Parameter	Type	Required	Description
file_type	string	yes	Always `docx_youtube`.
task_code	string	yes	Public GUID of the user task.

Example response (success)

Status: 200 OK
Headers: Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document; Content-Disposition: attachment; filename="youtube_report_task<ID>.docx"
Body: binary DOCX contents.

Errors (HTTP 200, JSON)

Code	Message (short)
4023	Unauthorized (missing/invalid JWT)
4045	Missing `task_code`
4021	Task not found for the user
4061	Invalid task type (`youtubenew` expected)
4062	Invalid task status (`completed` expected)
4057	No data (TaskResult is empty)
5002	DB error
5000	Generic internal error

TXT report for a YouTube task

GET /get_file?file_type=txt_youtube&task_code=<GUID>

Purpose. Generate and download a TXT report for a YouTube task.

curl -G "https://<host>/get_file" \
  -H "Authorization: Bearer <JWT>" \
  --data-urlencode "file_type=txt_youtube" \
  --data-urlencode "task_code=b7a62594-a664-4519-b0de-077b5522e245"

Parameter description (request)

Parameter	Type	Required	Description
file_type	string	yes	Always `txt_youtube`.
task_code	string	yes	Public GUID of the user task.

Example response (success)

Status: 200 OK
Headers: Content-Type: text/plain; charset=utf-8; Content-Disposition: attachment; filename="youtube_report_task<ID>.txt"
Body: text file.

Errors (HTTP 200, JSON)

Code	Message (short)
4023	Unauthorized (missing/invalid JWT)
4045	Missing `task_code`
4021	Task not found for the user
4061	Invalid task type
4062	Invalid task status
4057	No data
5002	DB error
5000	Generic internal error

Original call audio file

GET /get_file?file_type=audio&task_code=<GUID>

Purpose. Download the original audio file attached to a call task.

curl -G "https://<host>/get_file" \
  -H "Authorization: Bearer <JWT>" \
  --data-urlencode "file_type=audio" \
  --data-urlencode "task_code=b7a62594-a664-4519-b0de-077b5522e245"

Parameter description (request)

Parameter	Type	Required	Description
file_type	string	yes	Always `audio`.
task_code	string	yes	Public GUID of the user task.

Example response (success)

Status: 200 OK
Headers: Content-Type: audio/* (based on the original file); Content-Disposition: attachment; filename="<original-or-server-name>"
Body: binary audio contents.

Errors (HTTP 200, JSON)

Code	Message (short)
4023	Unauthorized (missing/invalid JWT)
4045	Missing `task_code`
4021	Task not found for the user
4046	File not found on disk
5002	DB error
5000	Generic internal error

11) Error codes

Contains the full list of API error codes and their meaning — from invalid data formats to internal server errors.

Below are the possible API error codes.

Code	Description
4001	Invalid data/parameter format
4002	Required parameter is missing
4012	Invalid/expired token
4020	`task_code` is not specified
4021	Task not found
4023	Unauthorized
4024	File not uploaded / download error
4025	Unsupported file format
4026	File decoding/encoding error
4030–4037	User validation errors
4033	User not found
4034	Plan (tariff) not found
4041	Resource is unavailable
4043	Invalid YouTube link
4044	No active plan (tariff)
4045	Required fields are missing
4046	Amount/currency does not match the plan
4047	Unsupported `file_type` or currency
4050	Insufficient plan resources
4052	Failed to determine audio duration
4053	Checklist/record not found
4054	Duplicate checklist question
4055	Cannot edit — answers already exist
4056	Access denied
4057	Analysis/result data not found
4060	`start_date`/`end_date` were not provided
4061	Invalid date format
4062	`start_date` is later than `end_date`
4070	DOCX library is unavailable
5000	Internal error
5002	Database error
5003	Report generation error

12) Plans & Pricing

Base rates

Calls: 0.08 €/min
Chats: 0.01 € per 50 KB

Minute/message discounts

Discounts apply only for Enterprise and Enterprise+ plans.

Plan	Discount	Price per minute	Price per chat
Pro	—	0.08 €	0.01 €
Enterprise	−10%	0.072 €	0.009 €
Enterprise+	−20%	0.064 €	0.008 €

Package table

Plan	Included in the package	Unit price inside the package	Package price (€)	Overage in this plan
Pro	5,000 min + 5,000 chats	0.08 €/min, 0.01 €/chat	400 € ~~450 $~~	0.08 €/min, 0.01 €/chat
Enterprise	10,000 min + 10,000 chats	0.072 €/min, 0.009 €/chat	600 € ~~820 $~~	0.072 €/min, 0.009 €/chat
Enterprise+	>10,000 min and/or >10,000 chats	0.064 €/min, 0.008 €/chat	volume-based	0.064 €/min, 0.008 €/chat

What is included in all plans

Interaction storage — 1 year
31 business reports per month, 31 daily reports per month
Unlimited number of operator quality reports

Audio-dialog transcription without analytics

Price: 0.02 €/min

On-premise deployment (inside the company perimeter)

Item	One-time (EUR)	Recurring (EUR)	Brief description	Throughput (approx.)
Hardware (2× DGX Spark)	26,000 €	—	2-node cluster based on Grace Blackwell Superchip	Audio: 15,000–30,000 min/day • Chats: 50,000–120,000/day
Transcripto software license	16,000 €	—	Transcription & analytics platform	—
Total one-time (hardware + software + rollout)	42,000 €	—	Delivery, installation, on-prem deployment, documentation, acceptance	—
Support (updates, support, Jira)	—	1,900 €/month	Regular updates, monitoring, support	—

For all questions, email info@transcripto.eu.

Introduction

How it works

1. Import calls and messages

2. Speech-to-text

3. Analysis and metric extraction

4. Reports and analytics

How to use the API

1. Authentication

2. Import calls or chats

3. Check task status

4. Retrieve analytics

5. Create a report generation task

6. Download the report file

1) Registration & authentication

User registration

Obtain a token (API KEY)

Parameter description (request)

Parameter description (response)

2) Account (Balance)

Get current balance and active plan details

Parameter description (request)

Example response (200)

Parameter description (response)

3) Tasks

Create a call processing task (file)

Parameter description (request)

Example response (200)

Parameter description (response)

Possible errors (HTTP 200, JSON)

Create a call processing task by URL

Parameter description (request)

Example response (200)

Parameter description (response)

Possible errors (HTTP 200, JSON)

Create an audio processing task (file)

Parameter description (request)

Example response (200)

Parameter description (response)

Possible errors (HTTP 200, JSON)

Create a YouTube processing task

Parameter description (request)

Example response (200)

Parameter description (response)

Possible errors (HTTP 200, JSON)

Create a chat analysis task (text)

Parameter description (request)

Example response (200)

Parameter description (response)

Create a report task (calls/chats)

Parameter description (request)

Example response (200)

Parameter description (response)

Possible errors (HTTP 200, JSON)

4) Retrieving results

Get all user tasks with the specified filters

Parameter description (request)

Example response (200)

Parameter description (response)

Get detailed task data

Parameter description (request)

Example response (200)

Parameter description (response)

Notes

Get call analysis for a task

Parameter description (request)

Example response (200)

Parameter description (response)

Notes

5) Checklists

Get active checklist questions

Parameter description (request)

Example response (200)

Parameter description (response)

Pagination

Create a checklist question

Parameter description (request)

Example response (200)

Parameter description (response)

Edit a checklist question

Parameter description (request)