API Reference Guide

overview exotel cqa (conversation quality analysis) provides ai powered quality analysis for contact center interactions the platform ingests interaction data audio recordings, transcripts, and metadata from any source, runs them through configurable quality profiles, and produces detailed quality scores this document covers the public api surface data import api push interactions into cqa via rest (single, batch, or file based) analysis api retrieve detailed quality analysis results file schemas csv format specifications for bulk ingestion base url all endpoints are served under the cqa context path https //cqa console in exotel com/ https //cqa console in exotel com/ authentication all data import and analysis api endpoints authenticate via an api key passed in the x api key header api surface auth method header data import api api key x api key {key} analysis api api key x api key {key} api keys api keys are scoped to a single account and are used for all programmatic ingestion and analysis retrieval api keys can be created and managed through the cqa dashboard rate limits api endpoints are rate limited per tenant (account) requests that exceed the limit receive 429 too many requests with error code rate limit exceeded (see response envelope) too many concurrent file jobs is a separate 429 with code too many jobs endpoint pattern method default tenant limit (typical) /ingress/interactions (ingest) post 100 requests per minute /ingress/ (tracking) get 300 requests per minute response envelope all data import and analysis api endpoints return responses in a common envelope success response { "status" 200, "request id" "d4f5a6b7 c8d9 4e0f a1b2 c3d4e5f6a7b8", "data" { } } error response { "status" 400, "request id" "d4f5a6b7 c8d9 4e0f a1b2 c3d4e5f6a7b8", "message" "descriptive error message", "error" { "code" "validation error" } } field type description status integer http status code mirrored in the body request id string unique request identifier for tracing and support message string human readable detail (present on many errors; may be omitted when redundant) data object response payload (present on success) error object present on failure contains code only error codes code http status description validation error 400 request failed validation (missing required fields, exceeded limits) invalid json 400 request body is not valid json invalid request 400 request contains invalid arguments unauthorized 401 missing or invalid api key not found 404 the requested resource was not found duplicate 409 returned for single ingest conflict responses (see ingest a single interaction) rate limit exceeded 429 tenant or user rate limit exceeded too many jobs 429 too many concurrent file ingestion jobs for this account internal error 500 an unexpected server error occurred conversation cap exceeded 429 account conversation cap exceeded daily, weekly, or monthly interaction limit reached data import api the data import api is the primary external integration point for pushing interaction data into cqa it supports three ingestion modes single, batch, and file based base path /api/v1/accounts/{account id}/ingress auth x api key header ingest a single interaction submits one interaction for quality analysis returns immediately with a tracking id post https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions request parameters (json body) content requirement at least one of audio url, transcript url, transcript text must be provided parameter name mandatory / optional type description external interaction id mandatory string your unique identifier for this interaction used for deduplication channel type mandatory string interaction channel recognized values voice, chat, email, sms, whatsapp other values are accepted (not rejected) source optional string identifies the originating system (e g my pbx, genesys) language optional string language code (e g en, hi, es) interaction start time optional string (iso 8601) when the interaction started (e g 2026 04 01t10 30 00z) duration seconds optional integer duration of the interaction in seconds audio format optional string audio format hint (e g wav, mp3, ogg) callback url optional string webhook url for status update notifications audio url mandatory if transcript url or transcript text is not provided string direct url to the audio recording transcript url mandatory if audio url or transcript text is not provided string direct url to the transcript file transcript text mandatory if neither audio url nor transcript url is provided string inline transcript/conversation text if both transcript text and transcript url are sent, transcript url wins (inline text is ignored) max 100 kb (utf 8) pii redacted optional boolean whether pii has already been redacted in the provided content default false if you have already redacted pii either by your own means or using the cqa provided capability , set this parameter as true (used internally to skip pii redaction again) metadata optional object arbitrary key value pairs for tagging maximum 50 keys values can be strings, numbers, or booleans example request (voice) url input voice call curl x post "https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions" \\ h "x api key {your api key}" \\ h "content type application/json" \\ d '{ "external interaction id" "call 2026 04 01 001", "channel type" "voice", "source" "my pbx", "language" "en", "interaction start time" "2026 04 01t10 30 00z", "duration seconds" 300, "audio format" "wav", "audio url" "https //storage example com/recordings/call 001 wav", "pii redacted" false, "callback url" "https //my app example com/webhooks/cqa", "metadata" { "agent id" "agent 42", "campaign" "retention q2", "disposition" "resolved" } }' example request (chat with url) curl x post "https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions" \\ h "x api key {your api key}" \\ h "content type application/json" \\ d '{ "external interaction id" "chat 2026 04 01 001", "channel type" "chat", "source" "whatsapp", "language" "en", "interaction start time" "2026 04 01t10 30 00z", "transcript url" "https //storage example com/messages/chat 001 txt" }' example request (chat with transcript text) curl x post "https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions" \\ h "x api key {your api key}" \\ h "content type application/json" \\ d '{ "external interaction id" "chat 2026 09 03 001", "channel type" "chat", "source" "web chat", "language" "en", "transcript text" "agent hello! how can i help you today?\ncustomer i need to reset my password \nagent sure, i can help with that let me send you a reset link " }' response 201 created interaction queued successfully { "status" 201, "request id" "req abc 123", "message" "queued for processing", "data" { "interaction id" "550e8400 e29b 41d4 a716 446655440000", "external interaction id" "call 2026 04 01 001", "status" "queued" } } 409 conflict duplicate external interaction id { "status" 409, "request id" "req abc 124", "message" "duplicate interaction with this external interaction id already exists", "error" { "code" "duplicate" } } 429 too many requests conversation cap exceeded { "status" 429, "request id" "req abc 126", "message" "daily conversation cap exceeded 50/50", "error" { "code" "conversation cap exceeded" } } 400 bad request validation error { "status" 400, "request id" "req abc 125", "message" "metadata must not exceed 50 keys", "error" { "code" "validation error" } } response fields parameter name type description interaction id string (uuid) cqa assigned unique identifier for the interaction external interaction id string your identifier, echoed back status string queued on success message string top level hint on 201 (e g queued) on errors, the detail text is in message, not inside error ingest a batch of interactions submits up to 100 interactions as a single asynchronous job returns an id in data for tracking post https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions/batch request parameters (json body) parameter name mandatory / optional type description interactions mandatory array list of interaction objects, each following the same schema (audio url or transcript url or transcript text \[max 100 kb / 102400 bytes]) as the single ingest endpoint minimum 1, maximum 100 note transcript text is supported in batch items each item can include at most 100 kb (102400 bytes) of transcript text if any batch item exceeds this limit, the entire batch request is rejected immediately with 400 validation error; no batch job is created response fields parameter name type description id string unique identifier for the batch job use this with the batch tracking endpoint type string always batch for this endpoint status string pending the job has been accepted and is queued for processing batch submission may return partial acceptance if some items fail request time validation while others are valid, the api returns 202 accepted and may include \ message \ accepted \ rejected \ errors in this case, valid items are queued for processing and invalid items are rejected immediately submit a file for ingestion submits a remote csv file url for asynchronous ingestion cqa downloads and processes the file in the background post https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions/files request parameters (json body) parameter name mandatory / optional type description file url mandatory string url to the file supported schemes https //, http //, s3 // https is strongly recommended; http is accepted but offers no transport encryption private/local addresses (localhost, 127 0 0 1, 10 x, 192 168 x, 172 16 x) are rejected format mandatory string file format csv or ndjson source optional string default source applied to all rows where the row level source is not set pii redacted optional boolean default pii flag applied to all rows callback url optional string default callback url stored per row (same semantics as single ingest; no http callback from ingress) column mapping optional object maps your csv headers to canonical column names keys are your original headers (trimmed, lowercased); values are canonical names ignored for ndjson see csv schema for canonical names metadata optional object default metadata merged into every row after merge, each row should respect the 50 key metadata limit enforced for batch/single ingest; avoid large default maps that push merged rows over the limit note for file ingestion, invalid rows are processed asynchronously and appear as rejected rows in the file job results file processing limits limit default value max rows per file job 100,000 max file size 100 mb get interaction by id retrieves the current status and details of an ingested interaction get https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions/{interaction identifier} path parameters parameter name mandatory / optional description account id mandatory your cqa account id interaction identifier mandatory either the cqa assigned uuid (interaction id) or your external interaction id response fields parameter name type description interaction id string (uuid) cqa assigned unique identifier external interaction id string your identifier batch id string job/batch id if the interaction was part of a batch or file job omitted for single ingestion channel type string channel type as submitted source string originating system status string current status queued, processing, completed, or failed status modified at string (iso 8601) when the status last changed failure reason string reason for failure only present when status is failed; omitted otherwise audio url string resolved audio recording url (same value as submitted audio url / files audio url) transcript url string resolved transcript url pii redacted boolean whether pii was flagged as redacted created at string (iso 8601) when the interaction was ingested metadata object key value metadata analyses array list of analyses triggered for this interaction each contains analysis id, profile id, and status interaction status lifecycle applies to the status field on individual interactions and analyses api status meaning queued interaction accepted, waiting to be processed processing analysis is underway completed all analyses finished successfully failed processing failed (check failure reason) job status lifecycle applies to the status field in the batch/file 202 response and the job status field in the batch tracking response job statuses are distinct from interaction statuses job status meaning pending job accepted and queued returned in the initial 202 response processing a worker has picked up the job and is processing rows completed all rows have been processed (check accepted/rejected for counts) failed the job failed entirely (check error message) track batch / file job retrieves all interactions for a batch or file job, with pagination and job level status get https //{host}/cqa/api/v1/accounts/{account id}/ingress/interactions/batch/{id} path parameters parameter name mandatory / optional description account id mandatory your cqa account id id mandatory the job identifier the id returned in the batch or file 202 response (data id) query parameters parameter name default max description page 0 zero based page index size 20 100 number of interactions per page values above 100 are silently clamped to 100 response fields parameter name type description id string the job identifier (same as data id from the batch or file 202 response) total integer total interactions associated with this job interactions array paginated list of interaction detail objects pagination object contains page, size, total elements, total pages job status string overall job status pending, processing, completed, or failed job type string batch or file total rows integer total rows found in the input (includes accepted + rejected) accepted integer number of rows successfully processed rejected integer number of rows that failed validation errors array up to 100 error entries each has line (row number), reason, and external interaction id error message string top level error message if the entire job failed completed at string (iso 8601) when the job finished processing note for batch submissions, some request time validation failures may be returned directly in the initial post /ingress/interactions/batch response use the submit response for request time rejected items; the tracking endpoint primarily reflects accepted items that entered processing analysis api retrieve detailed quality analysis results for a completed analysis base path /api/v1/accounts/{account id}/analyses auth x api key header list analyses returns a paginated list of completed analyses matching the given filters date filter is mandatory; max range is 31 days post https //{host}/cqa/api/v1/accounts/{account id}/analyses?limit={limit}\&offset={offset} query parameters parameter name default max description limit 20 100 number of results per page offset 0 10000 zero based result offset for pagination request parameters (json body) parameter name mandatory / optional type description other filters mandatory array list of filter objects must include at least one date filter quality profile uid optional string filter by quality profile uuid metadata filter group optional array of arrays nested filter conditions on interaction metadata each inner array is an and group; outer array is or filter objects ( other filters ) date filter (mandatory) field value field "date" operator "range" value object with start date and end date in yyyy mm dd or iso 8601 format max range 31 days score filter (optional) field value field "score" operator "greater than", "less than", "greater than or equal", "less than or equal", or "equals" value numeric score value example request curl x post "https //{host}/cqa/api/v1/accounts/{account id}/analyses?limit=5\&offset=0" \\ h "x api key {your api key}" \\ h "content type application/json" \\ d '{ "other filters" \[ {"field" "date", "operator" "range", "value" {"start date" "2026 07 01", "end date" "2026 07 15"}}, {"field" "score", "operator" "greater than or equal", "value" 9} ] }' response 200 ok { "status" 200, "request id" "51f6705d 6639 41ed 9029 d6053c5df1c2", "data" { "analyses" \[ { "analysis id" "9f77853f c4d4 482c 9651 b13394d65020", "interaction id" "a30f0175 2ba0 46d8 8002 5b84667bfb44", "external interaction id" "file 7b1eeafb f720 40bb 862f 60107f118e93", "profile id" "e7d721ce 035d 4f79 ab62 e9cc2138f449", "status" "completed", "ai score" 19 0, "qa score" 21 0, "final score" 21 0, "criticality adjusted score" 21 0, "metadata" { "source" "testevaluation", "agent id" "qa user", "campaign id" "100" }, "created at" "2026 05 29t17 16 46 259993+05 30" } ], "pagination" { "limit" 5, "offset" 0, "total" 1 } } } response fields parameter name type description analysis id string (uuid) unique analysis identifier interaction id string (uuid) the interaction this analysis belongs to external interaction id string your interaction identifier may be null if the interaction record is unavailable profile id string quality profile used for scoring status string completed, failed, or queued ai score float ai generated quality score qa score float manual qa score omitted if no manual review final score float effective score (qa if present, otherwise ai) criticality adjusted score float score after criticality weights metadata object interaction metadata created at string (iso 8601) when the analysis was created, in tenant timezone pagination field type description limit integer requested page size offset integer current offset total long total matching results across all pages error responses scenario http status error code example message missing date filter 400 validation error "date filter is required provide a date filter with start date and end date in other filters " date range > 31 days 400 validation error "date range must not exceed 31 days" start date after end date 400 validation error "start date must be before or equal to end date" invalid date format 400 validation error "invalid start date format expected yyyy mm dd or iso 8601" invalid score operator 400 validation error "unsupported score filter operator" limit out of range 400 validation error "limit must be between 1 and 100" offset out of range 400 validation error "offset must be between 0 and 10000" get analysis detail returns the full scoring breakdown for a specific analysis, including categories, subcategories, and individual kpi scores get https //{host}/cqa/api/v1/accounts/{account id}/analyses/{analysis id} path parameters parameter name mandatory / optional description account id mandatory your cqa account id analysis id mandatory the analysis uuid (obtained from the interaction detail's analyses array) response fields parameter name type description analysis id string (uuid) unique analysis identifier interaction id string (uuid) the interaction this analysis belongs to external interaction id string your interaction identifier profile id string quality profile used for scoring profile name string human readable quality profile name status string queued, processing, completed, or failed ai score float ai generated quality score qa score float manual qa score (if a human reviewer overrode) omitted if no manual review has occurred final score float effective score (qa score if present, otherwise ai score) criticality adjusted score float score after applying criticality weights max score float maximum possible score for this profile analysis completed at string (iso 8601) timestamp derived from the interaction's last status change in the account timezone (not a separate analysis completion clock) may not equal a pure "analysis finished" instant in all edge cases failure reason string not populated in the current response (null omitted) use status and support channels when an analysis fails categories array scored categories see category object below metadata object interaction metadata, echoed for convenience category object field type description name string category name (e g "communication skills") ai score float ai score for the category qa score float manual qa score for the category omitted if not set final score float final score for the category criticality adjusted score float criticality adjusted score max score float maximum possible score sub categories array subcategories within this category subcategory object field type description name string subcategory name qa score float manual qa score for the subcategory omitted if not set kpis array individual kpis scored within this subcategory kpi object field type description kpi name string kpi name (e g "proper greeting") ai response string the ai's answer (e g "yes", "no", "partially") ai justification string the ai's reasoning for its score ai suggestion string optional ai suggestion text omitted if not set ai score float ai score for this kpi qa score float manual qa score for this kpi omitted if not set qa justification string qa justification text omitted if not set qa selected kpi option uid string uid of the kpi option selected by qa, if any qa selected kpi option value string label/value of the qa selected kpi option user comment string free text qa/user comment on this kpi final score float final score (may reflect qa override) criticality adjusted score float criticality adjusted score max score float maximum possible score for this kpi file schemas when using the file based ingestion endpoint (post /interactions/files), cqa supports two file formats csv and ndjson csv schema the first row of a csv file must contain column headers headers are trimmed and lowercased before matching against canonical names canonical column names column required type description external interaction id yes string your unique interaction identifier channel type yes string voice, chat, email, sms, whatsapp source no string originating system identifier language no string language code (e g en) interaction start time no iso 8601 string iso 8601 utc format (e g 2026 04 01t10 00 00z) duration seconds no integer interaction duration in seconds audio format no string format hint (e g wav, mp3) callback url no string per row callback url (stored; no http callback from ingress) pii redacted no boolean true or false audio url yes (mandatory if transcript url or transcript text is not provided) string audio file url(s) supports multiple urls separated by ; transcript url yes (mandatory if audio url or transcript text is not provided) string transcript file url(s) supports multiple urls separated by ; transcript text yes (mandatory if audio url or transcript url is not provided) string actual transcript text of the conversation if both transcript url and transcript text are provided, transcript url wins file url no string generic file url used with file type as a fallback when no audio url/transcript url entries exist file type no string file extension for type resolution audio extensions mp3, wav, ogg, flac, m4a, aac, wma, amr transcript extensions txt, pdf, doc, docx, srt, vtt content requirement each row must have at least one of audio url, transcript url, transcript text extra columns become metadata any column header that is not in the canonical set above is automatically added to the row's metadata map for example, columns named agent, campaign, or disposition become metadata key value pairs without any extra configuration column mapping if your csv uses non standard headers, supply a column mapping object in the file submission request to rename them keys are your original headers (trimmed, lowercased); values are canonical names example given a csv with headers call id,type,recording,agent,campaign { "column mapping" { "call id" "external interaction id", "type" "channel type", "recording" "audio url" } } after mapping, agent and campaign are not canonical, so they automatically become metadata example csv external interaction id,channel type,audio url,transcript url,transcript text,language,agent,campaign call 001,voice, https //s3 example com/rec 001 wav,,,en,agent 42,retention https //s3 example com/rec 001 wav,,,en,agent 42,retention call 002,voice, https //s3 example com/rec 002 wav,,,hi,agent 15,support https //s3 example com/rec 002 wav,,,hi,agent 15,support chat 001,chat,,,agent hello! how can i help you today?\ncustomer i need to reset my password ,en,agent 42,retention call 003,chat,,,,agent 42,retention note chat 001 is valid via transcript text call 003 fails because it has no audio url, transcript url, or transcript text request level defaults for file ingestion for both csv and ndjson file submissions, fields set on the post /interactions/files request body are applied as defaults to every row request field behavior source applied to rows where the row level source is null or empty pii redacted applied to rows where the row level value is null callback url applied to rows where the row level value is null metadata merged with each row's metadata row level keys take precedence webhooks / callbacks when a callback url is provided (on the single ingest request, in the batch/file request, or per csv row), cqa delivers http post notifications to that url at key points in the interaction's or file job’s lifecycle delivery method http post content type application/json timeout 10 seconds (connect and read) feature flag webhook delivery is controlled by the feature flag if the flag is disabled for the tenant, callback url values are stored but no http requests are made event types event trigger interaction ingested interaction has been accepted and persisted interaction analysis in progress analysis has started for a quality profile interaction analysis completed a single analysis completed successfully payload includes scores and kpi results interaction analysis failed a single analysis failed payload includes error details interaction dispute raised a qa dispute has been raised on an analysis interaction dispute resolved a qa dispute has been resolved file ingestion completed a file ingestion job has finished processing payload structure every callback post body is a json object with these top level fields field type description event string the event type (see table above) deliveryid string (uuid) unique identifier for this delivery attempt timestamp string (iso 8601) when the callback was generated (e g 2026 04 01t10 35 42 123z) accountid string your account identifier interactionid string (uuid) cqa's internal interaction identifier present for interaction level events externalinteractionid string your external interaction id present when available data object event specific data contents vary by event type (see below) data by event type interaction ingested { "status" "ingested" } interaction analysis in progress { "analysisid" "a1b2c3d4 e5f6 7890 abcd ef1234567890", "profileid" "prof 001", "profilename" "inbound support" } interaction analysis completed { "analysisid" "a1b2c3d4 e5f6 7890 abcd ef1234567890", "status" "completed", "profileid" "prof 001", "aiscore" 85 0, "qascore" null, "finalscore" 85 0, "criticalityadjustedscore" 85 0, "analysiscompletedat" "2026 04 01t10 35 42z", "kpiresults" \[ { "kpiid" "kpi 101", "categoryid" "cat 01", "subcategoryid" "subcat 01", "airesponse" "yes", "aijustification" "the agent greeted the customer by name ", "aiscore" 5 0, "qascore" null, "finalscore" 5 0, "criticalityadjustedscore" 5 0 } ] } the kpiresults array is included when kpi level results are available each entry contains the kpi identifier, its category/sub category, the ai's response and justification, and individual scores interaction analysis failed { "errorcode" "analysis failed", "errormessage" "transcript processing timed out" } interaction dispute raised { "analysisid" "a1b2c3d4 e5f6 7890 abcd ef1234567890", "disputeid" "d1e2f3a4 b5c6 7890 abcd ef1234567890" } interaction dispute resolved { "analysisid" "a1b2c3d4 e5f6 7890 abcd ef1234567890", "disputeid" "d1e2f3a4 b5c6 7890 abcd ef1234567890", "resolution" "accepted", "updatedscore" 90 0 } file ingestion completed { "filejobid" "job 2026 04 01 001", "status" "file ingestion completed", "totalrows" 500, "accepted" 498, "rejected" 2, "completedat" "2026 04 01t11 05 00z", "errors" \[ { "row" 42, "reason" "missing required field external interaction id" } ] } full example a complete callback payload for a completed analysis { "event" "interaction analysis completed", "deliveryid" "f47ac10b 58cc 4372 a567 0e02b2c3d479", "timestamp" "2026 04 01t10 35 42 123z", "accountid" "e067e113f4", "interactionid" "550e8400 e29b 41d4 a716 446655440000", "externalinteractionid" "call 2026 04 01 001", "data" { "analysisid" "a1b2c3d4 e5f6 7890 abcd ef1234567890", "status" "completed", "profileid" "prof 001", "aiscore" 85 0, "qascore" null, "finalscore" 85 0, "criticalityadjustedscore" 85 0, "analysiscompletedat" "2026 04 01t10 35 42z", "kpiresults" \[ { "kpiid" "kpi 101", "categoryid" "cat 01", "subcategoryid" "subcat 01", "airesponse" "yes", "aijustification" "the agent greeted the customer by name ", "aiscore" 5 0, "qascore" null, "finalscore" 5 0, "criticalityadjustedscore" 5 0 } ] } } security hmac signature each callback request includes headers for verifying authenticity header description x cqa signature hmac sha256 signature of the request body, formatted as sha256=\<hex> x cqa timestamp iso 8601 timestamp of when the request was sent (e g 2026 04 01t10 35 42 123z) to verify a callback extract the hex digest from x cqa signature (strip the sha256= prefix) compute hmac sha256(secret, requestbody) using your api key secret as the signing key compare the computed hex digest with the value from step 1 the signing secret is derived from your active api key it is shared during onboarding retry policy if the callback endpoint returns a 5xx or 429 status code (or the request times out), cqa retries delivery a total of 3 attempts are made (1 initial + 2 retries) attempt delay before attempt 1st (initial) immediate 2nd (1st retry) 10 seconds 3rd (2nd retry) 30 seconds after 3 failed attempts, the delivery is marked as failed callbacks that receive 2xx or 4xx (other than 429) responses are not retried limits and constraints constraint value max interactions per batch 100 max metadata keys per interaction 50 (enforced on single/batch request bodies; keep merged file row metadata within this bound) max rows per file job 100,000 max file size per file job 100 mb max concurrent file jobs per account 5 (default) batch tracking page size (max) 100 (silently clamped) supported file formats csv, ndjson supported file url schemes https, http, s3 (https recommended) supported channel types voice, chat, email, sms, whatsapp max transcript text 100 kb (utf 8) conversation cap (trial accounts) 300 per month (default when no cap is explicitly configured) external interaction id,channel type,audio url,transcript url,transcript text,language,agent,campaign call 001,voice, https //s3 example com/rec 001 wav,,,en,agent 42,retention https //s3 example com/rec 001 wav,,,en,agent 42,retention call 002,voice, https //s3 example com/rec 002 wav,,,hi,agent 15,support https //s3 example com/rec 002 wav,,,hi,agent 15,support chat 001,chat,,,agent hello! how can i help you today?\ncustomer i need to reset my password ,en,agent 42,retention call 003,chat,,,,agent 42,retention