Skip to content

Converz Data API (1.0.5)

The Converz API lets you update and sync data about users, conversations and analytics into your own systems.

Overview

Use this API to:

  • List, export, and update users and their attributes
  • List, export, and update conversations with metadata and analytics
  • Retrieve analytics that aggregate metrics across time, users, vendors, campaigns and more

Typical use cases:

  • Load Converz data (like automatically generated summaries) into your data warehouse or CRM
  • Build custom dashboards for operations / team leads
  • Enrich internal tools with conversation and user metrics

Core concepts

  • user – a support agent / user in your Converz environment (identified by rep_id)
  • conversation – a single customer interaction with metadata, timing and analytics (identified by call_id)
  • analytics – aggregated metrics over conversations and/or in-app user activity

Base URL

All endpoints are served under:

https://yourdomain.converz.co/api/v1

Authentication

All requests must be authenticated. Include your API key in every request header, for example:

X-API-Key: YOUR_API_KEY

Replace YOUR_API_KEY with a valid key for your environment. Keys are provisioned by Converz.

Getting started

  1. Obtain an API key from your Converz contact.
  2. Make a test request to GET /reps?n_per_page=1 to verify connectivity (lists users).
  3. Use GET /calls to fetch conversation-level data for your desired period.
  4. Use GET /report to retrieve analytics over conversations and/or users.

Which endpoints should I use?

For most integrations, use the JSON, row-based endpoints:

  • GET /reps – primary listing endpoint for users
  • GET /calls – primary listing endpoint for conversations
  • GET /report – primary endpoint for aggregated analytics
Download OpenAPI description
openapi.json
openapi.yaml
Overview
License
Proprietary
Languages
Servers
Mock server
https://docs.converz.co/_mock/openapi/
https://yourdomain.converz.co/api/v1/

Conversations

Operations

Analytics

Operations

Retrieve analytics

Request

This endpoint retrieves aggregated analytics over conversations and/or in-app user activity as JSON rows.

Use the query parameters to:

  • Control the time range (start_date, end_date, or days)
  • Filter by dimensions such as vendor, rep_id, campaign, department, and subcampaign
  • Choose which metrics to include via the metric parameter

The groupby parameter controls how results are grouped, for example:

  • groupby=date → one row per calendar date
  • groupby=date,campaign → one row per date per campaign
  • groupby=rep_id → one row per user

Time variables week, month, and quarter automatically imply year. The half time variable groups data into an earlier and later half of the period.

Security
ApiKeyAuth
Query
start_datestring

Oldest date to include. Default: 30 days ago.

end_datestring

Newest date to include. Default: today.

daysinteger(int64)

Number of days to include up to and including end_date. Alternative to start_date. Default: 30

vendorArray of strings

Filter on one or more vendor values, default:null (unfiltered)

rep_idArray of strings

Filter on one or more rep_id values, default:null (unfiltered)

campaignArray of strings

Filter on one or more campaign values, default:null (unfiltered)

departmentArray of strings

Filter on one or more department values, default:null (unfiltered)

subcampaignArray of strings

Filter on one or more subcampaign values, default:null (unfiltered)

metricstring

Metric to calculate. Behavioral call metrics from Converz, or metrics attached via calls POST or /event POST.

groupbyArray of strings

One or more grouping variables. For example, groupby=date returns one row per calendar date, groupby=date,campaign returns one row per calendar date per campaign. Time variables week, month, and quarter automatically imply year. Time variable half doesn't refer to half of a year. Rather, it groups the data into an earlier and later half. Allowed values: date week month quarter year half vendor rep_id campaign department subcampaign metric.

curl -i -X GET \
  'https://docs.converz.co/_mock/openapi/report?start_date=string&end_date=string&days=0&vendor=string&rep_id=string&campaign=string&department=string&subcampaign=string&metric=string&groupby=string' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
object
Response
application/json
{}

Users

Operations