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

List conversations

Request

This endpoint returns conversations as JSON rows, e.g., [{"call_id":1,"rep_id":"kees500"},{"call_id":2,"rep_id":"cas501"},{"call_id":3,"rep_id":"kris502"}] This is the default format for retrieving conversation-level data and attributes.

Security
ApiKeyAuth
Query
n_per_pageinteger(int64)

Number of conversations per page, default:10, max:1000000

pageinteger(int64)

Page number, default:1

start_datestring

Filter by start_date e.g. 2025-07-15, default:null (unfiltered)

end_datestring

Filter by end_date e.g. 2025-07-15, default:null (unfiltered)

afterstring

Filter by min conversation start_time e.g. 2025-07-15 12:00, default:null (unfiltered)

beforestring

Filter by max conversation start_time e.g. 2025-07-15 12:00, default:null (unfiltered)

metricstring

Metric to calculate. Behavioral conversation metrics from Converz or metrics attached per conversation in app or via calls POST.

rep_idArray of strings

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

vendorArray of strings

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

campaignArray of strings

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

subcampaignArray of strings

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

departmentArray of strings

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

vendor_call_idstring

Filter by specific vendor call id(s), e.g., 5a9fdc24-685d-42d9-9862-4dbdb52f51e9, default:null (unfiltered)

columnsstring

Include only specific columns in the result, default:null (unfiltered)

curl -i -X GET \
  'https://docs.converz.co/_mock/openapi/calls?n_per_page=0&page=0&start_date=string&end_date=string&after=string&before=string&metric=string&rep_id=string&vendor=string&campaign=string&subcampaign=string&department=string&vendor_call_id=string&columns=string' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
object
Response
application/json
{}

Update one or more conversations by call_id.

Request

Update attributes on one or more conversations.

Input format can be columnar, e.g., {"call_id":[1,2],"campaign":["A","B"]}, or row-wise, e.g., [{"call_id":1,"campaign":"A"},{"call_id":2,"campaign":"B"}].

Note: if a variable is supplied for only some rows, the value will be set to null for other rows, e.g., [{"call_id":1,"campaign":"A"},{"call_id":2,"subcampaign":"B1"}] will set conversation 1's subcampaign to null and conversation 2's campaign to null.

A safe way to avoid bugs like this is to always use the columnar format, e.g., {"call_id":[1,2],"campaign":["A","B"]} doesn't set any values to null, or {"call_id":[1,2],"campaign":["A",null],"subcampaign":[null,"B1"]} only sets the subcampaign for conversation 2 and the campaign for conversation 1.

Max rows per request: 100000.

Security
ApiKeyAuth
Bodyapplication/json
object
curl -i -X POST \
  https://docs.converz.co/_mock/openapi/calls \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{}'

Responses

OK

Bodyapplication/json
object
Response
application/json
{}

Analytics

Operations

Users

Operations