Convirza API — v2 to v3 Gap Analysis

API v3 exposes a set of conversation analytics data points that v2 does not return, most notably a call’s Classification, its Scorecard details, and its overall Score. These analytics fields are available in API v3 only.

Two points to keep in mind while migrating:

1. v3 is not a field-for-field copy of v2. A few areas were redesigned in v3 for a cleaner structure; where that applies, it is called out below as “restructured.”
2. Call data that lived across several separate v2 endpoints is now consolidated into a single v3 endpoint with opt-in data modules (see the next section).

In v2, call data was spread across multiple endpoints, and you called a different one depending on what you wanted (call details, transcription, tags, custom sources, indicator scores, DNI, and so on).

In v3, this consolidates into a single call-reading surface:

You choose which additional data to embed using the include query parameter (comma-separated). For example:

GET /v3/conversations/calls/987654?include=scorecard,summary,dni_data,transcription

Available modules include custom_sources, tags, comments, indicators, summary, transcription, transcription_details, extended_caller, dni_data, and scorecard.

If a module is not named in include, it is not returned, so request exactly the modules you need.

The following data is new in v3 and has no equivalent in v2.

2a. Scorecard evaluation — include=scorecard

Returned as a single scorecard object on the call. It is null when the call has no scorecard attached or has not been scored.

2b. AI call summary — include=summary

2c. Voice agent data — voiceagent_data

Returned when the call involved a Convirza AI voice agent.

These existed in v2 but were restructured in v3 for clarity.

The following data existed in v2 as separate endpoints and is available in v3 by adding the corresponding module. There is no loss of data, only a change in how it is requested.

The AI-extracted caller name (ai_caller_identity) is available in both v2 and v3.

• Envelope. v3 responses are wrapped in { "code", "message", "data", "request_id", "timestamp" }. For Get Call By ID, the call object is at data.result, with modules nested under it.
• Opt-in modules. A module that is not named in an include is not returned. Request exactly the modules you need.
• Types. total_score is a number (0–100), outcome.answer is a boolean, and scorecard is null (rather than partial data) when the call is not scored.
• Timestamps. ISO 8601 UTC throughout (for example, call_started, scored_on).
• List endpoint. A limit is required (1–200). The date range defaults to the last 7 days and cannot exceed 31 days. Use offset for pagination; a total count is returned.
• Nullability. Analytics fields can be null. For example, classification is null on a small share of scored calls, and scorecard is null on calls that have not been scored. Handle nulls rather than assuming a value is always present.

To set expectations clearly, the following are not returned today:

• Scorecard audit trail and rescore history — the identity of who scored or reviewed a call, manual score adjustments, and prior-round scores.
• Per-call sentiment and keywords.

If any of these are important to your reporting, please let us know, and we can advise.

Base call fields (always returned):

call_id, provisioned_route_id, org_unit_id, disposition, duration, caller_id, phone_number, ring_to, default_ring_to, repeat_call, call_started, campaign_id, campaign_name, campaign_ext_id, user_id, group_name, ai_caller_identity.

Modules (opt-in via include):

• call_detail — bill_second, call_value, external_id, dni_log_id, is_outbound, cdr_source, call_ended, analytic_status, call_mine_status, call_created, mined_timestamp, ring_to_name, channel_id, channel_category, channel_sub_category, channel, recording_id.
• recording_details — recording_id, filename, url, expires_at, channel_layout, frequency, format, duration, bitrate, size.
• extended_caller — company_name, caller_name, address, city, state, zip_code, line_type.
• custom_sources — custom_source_id, custom_source_name, custom_source_created.
• tags — tag_id, ct_user_id, call_tag_created, tag_name, tag_created, tag_active.
• comments — note_id, call_id, note, created_on, updated_on, ct_user_id, first_name, last_name.
• indicators — indicator_id, score_id, score_value, indicator_name, external_id, indicator_active, indicator_created.
• Summary — AI call summary (new in v3).
• transcription — full transcript text.
• transcription_details — timestamped, speaker-labeled segments.
• dni_data — browser, created_at, custom_params, destination_url, dni_vid, first_page, ga_cid, ip_host, last_page, location_details, log_date, master_node_id, group_id, phone_number_details.
• voiceagent_data — voiceagent_id, voiceagent_name, outcome, summary, first_name, last_name, phone_number, requested_time, appointment_date, appointment_time, additional_info (new in v3).
• scorecard — scorecard_id, scorecard_name, scorecard_call_id, status, total_score, scored_on, outcome (question, answer), classification (name) (new in v3).