---
title: Convirza API — v2 to v3 Gap Analysis
description: Learn what's new in Convirza API v3 vs v2 for call reporting — including Scorecard, Score, Classification, AI Summary, and how to migrate your integration.
---
[Skip to content](https://kb.convirza.com/convirza-api-v2-to-v3-gap-analysis#main-content)
English
Show submenu for translations
[More support](https://kb.convirza.com/kb-tickets/new?hsLang=en)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [More support](https://kb.convirza.com/kb-tickets/new)
- Contact us
Contact us
How can we help you?
- There are no suggestions because the search field is empty.
1. [Knowledge Base](https://kb.convirza.com/?hsLang=en)
2. [Convirza API](https://kb.convirza.com/convirza-api?hsLang=en)
# Convirza API — v2 to v3 Gap Analysis
## This guide lists the additional call analytics data points available in API v3 that are not available in API v2, for teams migrating their reporting integration from v2 to v3. It covers the reporting flow only (reading call and conversation data); campaign and call-flow provisioning is not covered here.
**Summary**
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).
**1. How call data is read in v3**
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:
| Purpose | v3 endpoint |
| --- | --- |
| List calls (with filters, date range, pagination) | GET /v3/conversations/calls |
| Get one call by ID | GET /v3/conversations/calls/{id} |
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.
**2. New data points in v3 (not available in v2)**
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.
| Field | Type | Description | Available in v2 |
| --- | --- | --- | --- |
| scorecard.total\_score | number (0–100) | The overall score the call received on the scorecard. | No |
| scorecard.classification.name | string | The call classification (for example, Sales, Service, Spam, Wrong Number). | No |
| scorecard.outcome.answer | boolean | Whether the desired outcome was achieved (Yes/No). | Limited (v2 returned only a boolean, without the question) |
| scorecard.outcome.question | string | The outcome question being answered (for example, “Sale Made/Quote Sent?”, “Appointment Set?”). | No |
| scorecard.scorecard\_name | string | Name of the scorecard applied to the call. | Limited (v2 returned only a name string) |
| scorecard.scorecard\_id | number | ID of the scorecard applied. | No |
| scorecard.scorecard\_call\_id | number | ID of this specific scoring evaluation (supports rescoring). | No |
| scorecard.status | string | Scoring state: scored, reviewed, unscored, or needs\_scorecard. | No |
| scorecard.scored\_on | ISO 8601 UTC | Timestamp of when the call was scored. | No (available as a filter in v2, but not returned per call) |
### **2b. AI call summary — include=summary**
| Field | Type | Description | Available in v2 |
| --- | --- | --- | --- |
| summary | string | An AI-generated summary of the conversation. | No |
### **2c. Voice agent data — voiceagent\_data**
Returned when the call involved a Convirza AI voice agent.
| Field | Description |
| --- | --- |
| voiceagent\_id, voiceagent\_name | The AI voice agent that handled the call. |
| outcome, summary | Agent-determined outcome and summary. |
| first\_name, last\_name, phone\_number | Caller details captured by the agent. |
| requested\_time, appointment\_date, appointment\_time, additional\_info | Appointment and booking details captured by the agent. |
**3. Fields that changed shape between v2 and v3**
These existed in v2 but were restructured in v3 for clarity.
| Area | v2 | v3 |
| --- | --- | --- |
| Scorecard | A single string (the name) | An object with the fields listed in section 2a |
| Outcome | A single boolean | An object: { question, answer } |
| Recording | Recording URL and a few fields | A recording\_details object: url, expires\_at, filename, format, bitrate, frequency, channel\_layout, duration, size, recording\_id |
| Indicators | Indicator rows carried duplicated scorecard/outcome values | An indicators module, with scorecard data provided once at the call level rather than duplicated per indicator |
**4. Data available in both v2 and v3 (delivered via a module in v3)**
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.
| Data | v2 endpoint | v3 |
| --- | --- | --- |
| Extended call metadata | List Call Details | Base fields plus call\_detail |
| Caller identity/data append (name, company, address, city, state, ZIP, line type) | List Extended Call Details | include=extended\_caller |
| Transcription (full text) | List Calls With Transcription | include=transcription |
| Transcription detail (timestamps, speakers) | List Calls With Transcription Details | include=transcription\_details |
| Tags | List Calls With Tags | include=tags |
| Comments/notes | Call comment endpoints | include=comments |
| Custom sources | List Calls With Custom Sources | include=custom\_sources |
| Indicator scores | List Calls With Indicator Scores | include=indicators |
| DNI web/session data | List Calls With DNI | include=dni\_data |
The AI-extracted caller name (ai\_caller\_identity) is available in both v2 and v3.
**5. Response structure notes for the migration**
- **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.
**6. Not currently returned by the v3 reporting API**
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.
**7. Complete v3 call field reference**
**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).
---
*For questions on any field or on the migration, please contact Convirza Support.*
- [Getting Started](https://kb.convirza.com/getting-started?hsLang=en#main-content)
- [Configuring Your Account](https://kb.convirza.com/getting-started?hsLang=en#configuring-your-account)
- [Application How To](https://kb.convirza.com/application-how-to?hsLang=en#main-content)
- [Tips and Tricks](https://kb.convirza.com/application-how-to?hsLang=en#tips-and-tricks)
- [Integrations](https://kb.convirza.com/integrations?hsLang=en)
- [Convirza API](https://kb.convirza.com/convirza-api?hsLang=en)
- [Features & Settings](https://kb.convirza.com/features-settings?hsLang=en#main-content)
- [Spam Calls & STIR/SHAKEN](https://kb.convirza.com/features-settings?hsLang=en#spam-calls-stir-shaken)
- [DNI](https://kb.convirza.com/features-settings?hsLang=en#dni)
- [White Label](https://kb.convirza.com/features-settings?hsLang=en#white-label)
- [QR Codes](https://kb.convirza.com/features-settings?hsLang=en#qr-codes)
- [Data Append](https://kb.convirza.com/features-settings?hsLang=en#data-append)
- [Multi Language Support](https://kb.convirza.com/features-settings?hsLang=en#multi-language-support)
- [Telecom](https://kb.convirza.com/telecom?hsLang=en#main-content)
- [SMS](https://kb.convirza.com/telecom?hsLang=en#sms)
- [Number Porting](https://kb.convirza.com/telecom?hsLang=en#number-porting)
[](http://convirza.com)
[mailto:email@email.com](mailto:email@email.com)
Copyright © 2026, Convirza