Get Calls List

Returns a paginated list of inbound and outbound calls within a specified date range, with optional filtering and enrichment via the include parameter.

Date range (optional, defaults to last 7 days)
start_date and end_date are optional ISO 8601 timestamps (UTC). If omitted, the API returns calls from the last 7 days. The range must not exceed 31 days. end_date must be strictly greater than start_date.

Pagination
Use limit (1–200, required) and offset (0-based, default 0) to page through results. The response includes a total count so clients can calculate total pages.

Sorting

sort_by — field to sort by: call_started, duration, caller_id, phone_number (default: call_started).

sort_order — sort direction: asc, desc (default: desc).

Filtering
All filters are optional and can be combined:

org_unit_id — scope to a specific organizational unit (must be within your account hierarchy).

campaign_id — scope to a specific campaign.

provisioned_route_id — scope to a specific call flow / tracking number configuration.

call_id — retrieve a single call record by its unique identifier (forces single-record mode, ignores date range and pagination).

caller_id — filter by caller phone number (E.164 format, e.g. +15551234567).

phone_number — filter by the phone number the call came in on.

ring_to — filter by the destination number the call was routed to.

is_spam — filter by spam status (true for spam calls only, false for non-spam calls only, omit to include all).

disposition — filter by one or more call outcomes. Accepted values: ANSWERED, NO ANSWER, BUSY, FAILED, VOICEMAIL, ABANDONED, TRANSFERRED.

Optional module datasets (include)
Attach supplemental data blocks to each call record by listing module names (comma-separated or repeated param). Available modules: custom_sources, tags, comments, indicators, summary, transcription, transcription_details, extended_caller, dni_data, scorecard.

custom_sources — Custom source types 1-5 for campaign attribution and UTM tracking.

tags — Call tags attached by agents or automation rules.

comments — Agent notes and disposition comments.

indicators — Scorecard indicators with individual scores and pass/fail status per indicator.

summary — AI-generated call summary (brief overview of conversation).

transcription — Full AI-generated call transcription text.

transcription_details — Detailed transcription with speaker labels (Customer/Agent) and timestamps (HH:MM:SS format).

extended_caller — Caller contact details: company_name, caller_name, first_name, middle_name, last_name, address, city, state, zip_code, country_code, line_type.

dni_data — DNI tracking data: web session details, phone pool info, visitor location (IP, city, region), UTM parameters, referral source.

scorecard — Scorecard evaluation summary: scorecard name, total score, outcome (answer + question), classification.

Note: Recording URLs are included by default in recording_details (7-day signed URLs). Expired URLs return HTTP 410 Gone.

Authorization
Results are automatically scoped to the organizational units accessible to the authenticated user. Requesting an org_unit_id outside your account scope returns a 403 error.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://platform-api.convirza.com/v3/conversations/calls?start_date=&end_date=&limit=&offset=&call_id=&org_unit_id=&campaign_id=&provisioned_route_id=&disposition=&caller_id=&phone_number=&ring_to=&is_spam=&include=&sort_by=&sort_order=' \ --header 'Authorization: Bearer <token>'

{ "code": 200, "message": "Success", "data": { "total": 42, "calls": [ { "call_id": 987654, "provisioned_route_id": 1022, "org_unit_id": 1200, "disposition": "ANSWERED", "duration": 182, "caller_id": "18015551234", "phone_number": "18015557654", "ring_to": "18015550000", "default_ring_to": "18015550000", "repeat_call": false, "call_started": "2026-02-14T18:20:12.000Z", "campaign_id": 311, "campaign_name": "Roofing Q1", "campaign_ext_id": "EXT-001", "user_id": 1001, "group_name": "Roofing Division", "ai_caller_identity": "Jane Smith", "voiceagent_data": { "voiceagent_id": 42, "voiceagent_name": "Customer Support Agent", "outcome": true, "summary": "Customer scheduled appointment for roof inspection", "first_name": "John", "last_name": "Doe", "phone_number": "+15551234567", "requested_time": "2026-03-20T14:30:00.000Z", "appointment_date": "2026-03-20", "appointment_time": "14:30", "additional_info": { "service_type": "roof_inspection", "notes": "Prefer morning appointments" } }, "recording_details": { "recording_id": 1000, "filename": "76c1U4NX_1720457390749", "url": "https://api.convirza.com/v3/recordings/987654?secret=...&access=...&expires=...&file_name=76c1U4NX_1720457390749.mp3", "expires_at": 1775462400, "channel_layout": "mono", "frequency": "8000 Hz", "format": "wav", "duration": "00:41:36.60", "bitrate": "128 kb/s", "size": "39009kB" }, "call_detail": { "bill_second": 210, "call_value": 75, "external_id": "ext-call-abc123", "dni_log_id": "9d5f...", "is_outbound": false, "cdr_source": "CE", "call_ended": "2026-02-14T18:23:14.000Z", "analytic_status": "complete", "call_mine_status": "mined", "call_created": "2026-02-14T18:20:12.000Z", "mined_timestamp": "2026-02-14T18:25:00.000Z", "ring_to_name": "Sales Team", "channel_id": 4, "channel_category": "Digital", "channel_sub_category": "Paid Search", "channel": "Digital > Paid Search" }, "custom_sources": { "custom_source_type_1": { "custom_source_id": 445, "custom_source_name": "Google Ads", "custom_source_created": "2026-01-10T12:00:00.000Z" }, "custom_source_type_2": { "custom_source_id": 445, "custom_source_name": "Google Ads", "custom_source_created": "2026-01-10T12:00:00.000Z" }, "custom_source_type_3": { "custom_source_id": 445, "custom_source_name": "Google Ads", "custom_source_created": "2026-01-10T12:00:00.000Z" }, "custom_source_type_4": { "custom_source_id": 445, "custom_source_name": "Google Ads", "custom_source_created": "2026-01-10T12:00:00.000Z" }, "custom_source_type_5": { "custom_source_id": 445, "custom_source_name": "Google Ads", "custom_source_created": "2026-01-10T12:00:00.000Z" } }, "tags": [ { "tag_id": 1, "ct_user_id": 1001, "call_tag_created": "2026-02-14T18:30:00.000Z", "tag_name": "Lead", "tag_created": "2026-01-01T12:00:00.000Z", "tag_active": true } ], "comments": [ { "note_id": 123, "call_id": 987654, "note": "Customer asked for pricing details.", "created_on": "2026-02-14T18:40:00.000Z", "updated_on": "2026-02-14T18:42:00.000Z", "ct_user_id": 2001, "first_name": "Alex", "last_name": "Smith" } ], "indicators": [ { "indicator_id": 18, "score_id": 4567, "score_value": 82, "indicator_name": "Conversion", "external_id": "conv-01", "indicator_active": true, "indicator_created": "2025-12-01T00:00:00.000Z", "agent": "agent@email.com", "scorecard": "Sales Scorecard", "outcome": "won" } ], "summary": "Customer asked about financing.", "transcription": "Caller: I need a roof inspection...", "transcription_details": [], "extended_caller": { "company_name": "Acme Corporation", "caller_name": "John Smith", "first_name": "John", "middle_name": "Michael", "last_name": "Smith", "address": "123 Main Street", "city": "Salt Lake City", "state": "UT", "zip_code": "84101", "country_code": "US", "line_type": "VOIP" }, "dni_data": { "browser": "Chrome 120.0", "created_at": "2026-04-24T10:54:58.270Z", "custom_params": { "dvt": "c", "adid": "76691090763477", "source_code": "BING11", "search_keyword": "dental emergency" }, "destination_url": "https://example.com/contact", "dni_vid": "visitor-abc123", "first_page": "https://example.com/home", "ga_cid": "GA1.2.123456789.1234567890", "ip_host": "192.168.1.1", "last_page": "https://example.com/contact", "location_details": { "ip": "192.168.1.1", "country_code": "US", "country_name": "United States", "region_code": "CA", "region_name": "California", "city": "San Francisco", "zipcode": "94102", "latitude": 37.7749, "longitude": -122.4194, "metro_code": "807", "area_code": 415 }, "log_date": "2026-04-24T10:54:58.270Z", "master_node_id": 1, "group_id": 1200, "phone_number_details": [ { "dni_id": "dni-12345", "phone_number": "+15551234567", "element": "div#phone-button", "phone_number_id": null, "pool_id": 42, "number_last_used": "2026-04-24T10:00:00.000Z", "provisioned_route_id": 789 } ], "ref_param": { "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "spring_sale", "utm_term": "roofing+services", "utm_content": "banner_ad", "kw": "roofing services", "network": "search", "mt": "e", "pos": "1t1", "ad": "ad123", "site": "site456", "target": "target789", "mobile": "true", "q": "search query", "gclid": "Cj0KCQiA15yNBhDTARIsAGnwe0W6Jv7bP2JxxrsC3...", "dclid": "CMjQlPa...-", "gclsrc": "aw.ds", "trkid": "trk_abc123", "k_clickid": "abc123xyz" }, "referring": "Google", "referring_type": "organic", "referring_url": "https://www.google.com/search?q=roofing", "search_words": "roofing services near me", "session_id": "session-xyz789", "updated_at": "2026-04-24T11:00:00.000Z" }, "scorecard": { "scorecard_id": 123, "scorecard_name": "Sales V3", "scorecard_call_id": 456789, "status": "scored", "total_score": 82, "scored_on": "2026-05-13T14:32:00.000Z", "outcome": { "answer": true, "question": "Sale Made/Quote Sent?" }, "classification": { "name": "Sales Call" } } } ] }, "request_id": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-01-20T12:34:56.789Z" }

Get Calls List

Request

Responses