openapi: 3.0.3
info:
  title: Converz Data API
  version: 1.0.5
  description: >
    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
  license:
    name: Proprietary
    url: https://converz.co/msa
servers:
  - url: https://yourdomain.converz.co/api/v1
security:
  - ApiKeyAuth: []
paths:
  /calls:
    get:
      summary: List conversations
      description: >-
        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.
      operationId: getCalls
      tags:
        - Conversations
      parameters:
        - name: n_per_page
          in: query
          description: Number of conversations per page, default:10, max:1000000
          required: false
          schema:
            type: integer
            format: int64
        - name: page
          in: query
          description: Page number, default:1
          required: false
          schema:
            type: integer
            format: int64
        - name: start_date
          in: query
          description: Filter by start_date e.g. `2025-07-15`, default:null (unfiltered)
          required: false
          schema:
            type: string
        - name: end_date
          in: query
          description: Filter by end_date e.g. `2025-07-15`, default:null (unfiltered)
          required: false
          schema:
            type: string
        - name: after
          in: query
          description: >-
            Filter by min conversation start_time e.g. `2025-07-15 12:00`,
            default:null (unfiltered)
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: >-
            Filter by max conversation start_time e.g. `2025-07-15 12:00`,
            default:null (unfiltered)
          required: false
          schema:
            type: string
        - name: metric
          in: query
          description: >-
            Metric to calculate. Behavioral conversation metrics from Converz or
            metrics attached per conversation in app or via calls POST.
          required: false
          schema:
            type: string
        - name: rep_id
          in: query
          description: Filter on one or more rep_id values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: vendor
          in: query
          description: Filter on one or more vendor values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: campaign
          in: query
          description: Filter on one or more campaign values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: subcampaign
          in: query
          description: Filter on one or more subcampaign values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: department
          in: query
          description: Filter on one or more department values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: vendor_call_id
          in: query
          description: >-
            Filter by specific vendor call id(s), e.g.,
            `5a9fdc24-685d-42d9-9862-4dbdb52f51e9`, default:null (unfiltered)
          required: false
          schema:
            type: string
        - name: columns
          in: query
          description: >-
            Include only specific columns in the result, default:null
            (unfiltered)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
        default:
          description: Default response.
          content:
            application/json:
              schema:
                type: object
    post:
      summary: Update one or more conversations by call_id.
      description: >-
        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.
      operationId: updateCalls
      tags:
        - Conversations
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request - Invalid parameters or payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
        default:
          description: Default response.
          content:
            application/json:
              schema:
                type: object
  /report:
    get:
      summary: Retrieve analytics
      description: >-
        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.
      operationId: getReport
      tags:
        - Analytics
      parameters:
        - name: start_date
          in: query
          description: 'Oldest date to include. Default: 30 days ago.'
          required: false
          schema:
            type: string
        - name: end_date
          in: query
          description: 'Newest date to include. Default: today.'
          required: false
          schema:
            type: string
        - name: days
          in: query
          description: >-
            Number of days to include up to and including end_date. Alternative
            to start_date. Default: 30
          required: false
          schema:
            type: integer
            format: int64
        - name: vendor
          in: query
          description: Filter on one or more vendor values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: rep_id
          in: query
          description: Filter on one or more rep_id values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: campaign
          in: query
          description: Filter on one or more campaign values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: department
          in: query
          description: Filter on one or more department values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: subcampaign
          in: query
          description: Filter on one or more subcampaign values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: metric
          in: query
          description: >-
            Metric to calculate. Behavioral call metrics from Converz, or
            metrics attached via calls POST or /event POST.
          required: false
          schema:
            type: string
        - name: groupby
          in: query
          description: >-
            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.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
        default:
          description: Default response.
          content:
            application/json:
              schema:
                type: object
  /reps:
    get:
      summary: List users
      description: >-
        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.
      operationId: getReps
      tags:
        - Users
      parameters:
        - name: n_per_page
          in: query
          description: Number of users per page, default:10, max:1000000
          required: false
          schema:
            type: integer
            format: int64
        - name: page
          in: query
          description: Page number, default:1
          required: false
          schema:
            type: integer
            format: int64
        - name: department
          in: query
          description: Filter on one or more department values, default:null (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: rep_id
          in: query
          description: >-
            Filter on one or more rep_id values (users), default:null
            (unfiltered)
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: active
          in: query
          description: >-
            Filter on active status, default:null (unfiltered). Allowed values:
            0 1.
          required: false
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
        default:
          description: Default response.
          content:
            application/json:
              schema:
                type: object
    post:
      summary: Update one or more users by rep_id.
      description: >-
        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.
      operationId: updateReps
      tags:
        - Users
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request - Invalid parameters or payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
        default:
          description: Default response.
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key used to authorize requests. Contact Converz support or your
        account manager to obtain a key.
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
