# Converz Data API

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


Version: 1.0.5
License: Proprietary

## Servers

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

## Security

### ApiKeyAuth

API key used to authorize requests. Contact Converz support or your account manager to obtain a key.

Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[Converz Data API](https://docs.converz.co/_bundle/openapi.yaml)

## Conversations

### List conversations

 - [GET /calls](https://docs.converz.co/openapi/conversations/getcalls.md): 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.

### Update one or more conversations by call_id.

 - [POST /calls](https://docs.converz.co/openapi/conversations/updatecalls.md): 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.

## Analytics

### Retrieve analytics

 - [GET /report](https://docs.converz.co/openapi/analytics/getreport.md): 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.

## Users

### List users

 - [GET /reps](https://docs.converz.co/openapi/users/getreps.md): 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.

### Update one or more users by rep_id.

 - [POST /reps](https://docs.converz.co/openapi/users/updatereps.md): 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.