Lenses and checks

Custom checks are yes-or-no questions VOIX answers for each call, grouped in lenses. A lens describes a kind of call; VOIX decides per call which lenses apply and evaluates their checks. Reading and changing them needs a Full access key.

Lenses and checks are either organisation-wide or belong to one team. They are created at the level of the key: an organisation key creates organisation-wide ones, a team key creates them for its team. A team key can only change its own team’s lenses and checks.

Lenses

List lenses


GET https://api.voix.tech/public/v1/lenses


{
  "data": [
    {
      "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "name": "Collections",
      "description": "Calls with a debtor about an outstanding invoice: payment arrangements, promises to pay, disputes.",
      "mode": "auto",
      "active": true,
      "level": "organisation",
      "checkCount": 6,
      "createdAt": "2026-10-13T08:00:00.000Z",
      "updatedAt": "2026-10-13T08:00:00.000Z"
    }
  ]
}

Create a lens


POST https://api.voix.tech/public/v1/lenses

Field	Type	Required	Description
`name`	string	Yes	Up to 80 characters.
`description`	string	No	Up to 1,000 characters. With `mode` `auto`, VOIX compares each call with this description.
`mode`	string	No	`auto` (default): the lens applies only to calls that match its description. `enforced`: it applies to every call.
`active`	boolean	No	Default `true`.

Returns 201 with the lens.

Update a lens


PATCH https://api.voix.tech/public/v1/lenses/{id}

Send any of name, description, mode or active. Returns the updated lens.

Delete a lens


DELETE https://api.voix.tech/public/v1/lenses/{id}

Returns 204. A lens that still has checks returns 409: move its checks to another lens or delete them first. A check with results on past calls cannot be deleted, so move it instead.

Checks

List checks


GET https://api.voix.tech/public/v1/lenses/{id}/checks

Returns the checks in one lens. An unknown lens returns 404. To list the checks of every lens at once, use GET /checks, optionally filtered with ?lensId=.


{
  "data": [
    {
      "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "lensId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "subject": "Payment arrangement confirmed",
      "description": "The agent repeats the agreed amounts and dates before ending the call.",
      "active": true,
      "level": "organisation",
      "createdAt": "2026-10-13T08:00:00.000Z",
      "updatedAt": "2026-10-13T08:00:00.000Z"
    }
  ]
}

Create a check


POST https://api.voix.tech/public/v1/lenses/{id}/checks

The check joins the lens in the URL.

Field	Type	Required	Description
`subject`	string	Yes	Short name, up to 120 characters.
`description`	string	Yes	What has to happen for the check to pass, up to 2,000 characters.
`active`	boolean	No	Default `true`.


curl -X POST https://api.voix.tech/public/v1/lenses/9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b/checks \
  -H "Authorization: Bearer vx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Payment arrangement confirmed",
    "description": "The agent repeats the agreed amounts and dates before ending the call."
  }'

Returns 201 with the check. New and changed checks apply to calls analysed from then on.

Update a check


PATCH https://api.voix.tech/public/v1/checks/{id}

Send any of subject, description, active or lensId. Returns the updated check. Set active to false to stop evaluating a check while keeping its results.

Delete a check


DELETE https://api.voix.tech/public/v1/checks/{id}

Returns 204. A check that has results on past calls returns 409, so those results are kept: deactivate it with PATCH and {"active": false} instead.

The results per call are on GET /calls/{id}, under checks and lenses.