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

Users

Operations

List users

Request

This endpoint returns all users as JSON rows, e.g., [{"rep_id":"kees500","gender":"m","campaign":"sales"},{"rep_id":"cas501","gender":"m","campaign":"sales"},{"rep_id":"kris502","gender":"m","campaign":"service"}]. This is the default format for retrieving user attributes.

Security
ApiKeyAuth
Query
n_per_pageinteger(int64)

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

pageinteger(int64)

Page number, default:1

departmentArray of strings

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

rep_idArray of strings

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

activeinteger(int64)

Filter on active status, default:null (unfiltered). Allowed values: 0 1.

curl -i -X GET \
  'https://docs.converz.co/_mock/openapi/reps?n_per_page=0&page=0&department=string&rep_id=string&active=0' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
object
Response
application/json
{}

Update one or more users by rep_id.

Request

Update attributes on one or more users.

Input format can be columnar, e.g., {"rep_id":["mila","liam"],"gender":["f","m"]}, or row-wise, e.g., [{"rep_id":"mila","gender":"f"},{"rep_id":"liam","gender":"m"}].

Note: if a variable is supplied for only some rows, the value will be set to null for other rows, e.g., [{"rep_id":"mila","gender":"f"},{"rep_id":"liam","name":"Liam"}] will set mila's name to null and liam's gender to null.

A safe way to avoid bugs like this is to always use the columnar format, e.g., {"rep_id":["mila","liam"],"gender":["f","m"]} doesn't set any values to null, or {"rep_id":["mila","liam"],"gender":["f",null],"name":[null,"Liam"]} only sets the name for liam and the gender for mila.

Max rows per request: 100000.

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

Responses

OK

Bodyapplication/json
object
Response
application/json
{}