Focus API Reference
REST API for Subphonic Focus — conversation intelligence and compliance recording. Use it to search and retrieve recorded communications (calls, Microsoft Teams, SMS, email), the people and endpoints behind them, retention groups, comments and users.
Authenticate with POST /authWithApiKey to exchange an API key for a short‑lived bearer JWT; every other call carries that token and is authorised per‑endpoint by the roles and rights listed on it.
This is the public, read‑only surface of the Focus API — only read and search endpoints (plus authentication) are documented. Write, update and delete operations exist on the API but are reserved for first‑party Focus tooling and are not published here. Contact support if your use case needs one.
Available integrations
The Native REST API is one of several ways to get data in and out of Focus, and they are all documented in this section. Pick the one that matches your access pattern:
| Integration | Description |
|---|---|
| Native REST API | Core Focus API for recordings, users, people & comments — on‑demand retrieval and detailed querying. |
| Cursor Synchronisation | Pull‑model bulk metadata sync via cursor‑based pagination. |
| Transcript Hook (Push API) | Event‑driven transcript‑completion notifications (low volume). |
| SFTP | Legacy bulk audio and metadata delivery over SFTP. |
| NICE NTR/NTX | NICE recording platform integration. |
| SMS to Email | Legacy notification integration that forwards each SMS as an email. |
Integration examples
Not sure how the pieces fit together? These worked examples describe common integration patterns at a high level — the shape of the solution and the calls involved — before you drop into the per-endpoint detail.
| Example | Use it when |
|---|---|
| Third-party application integration | You want to surface Focus recordings, transcripts and media in context inside another tool — a CRM, a QA dashboard, an eDiscovery or surveillance platform — reading live and on demand. |
| Local synchronisation with the Cursor API | You want to keep your own copy of all communications in sync — for example a job that runs every few hours and pulls any new calls into your data store. |
Two ways to read these REST API docs
The Focus API is documented in two complementary styles, and it's worth understanding why before you start — you'll move between them as you build.
| Guided integration walkthrough | OpenAPI reference (this section) | |
|---|---|---|
| Where | Native Focus REST API | You are here — Focus API |
| How it's written | Hand‑crafted by our team | Auto‑generated from the live OpenAPI spec |
| Best for | Understanding the flow: how calls fit together end‑to‑end | Understanding a single endpoint: exact request/response schema |
| Contains | Narrative quickstart, curl examples, a "find a call → get the transcript → download the audio" walkthrough, pagination, errors, rate limits, a capability matrix | Every parameter and field typed and described, live example values, and an interactive "Try it" console you can call the real API from |
Why both exist
- The hand‑crafted guide teaches the shape of an integration. A machine‑generated reference can tell you what
recording.searchaccepts, but it can't tell you that you'll typically call it first, take thethirdPartyIdfrom each result, and feed that into audio download. The walkthrough encodes that opinionated, real‑world flow — the context a spec can't carry. - The OpenAPI reference is the source of truth for detail. It's generated directly from the API, so field names, types and enums are always exactly what the deployed service expects — never drifting out of date. It also gives you a live console to try calls without writing any code.
In practice: start in the guided walkthrough to learn the end‑to‑end flow, then jump into the OpenAPI reference below for the precise schema of each call and to try it live. Every endpoint in the walkthrough links straight to its OpenAPI page, and vice‑versa.
Getting started
You need three things from your Focus account before you can make a call — all shown together in Admin → Account → Integrations → Native Focus REST API once a Super User enables the API:
| Item | What it is |
|---|---|
| API key | Secret used to obtain a token. Treat it like a password. |
clientId | Your numeric Focus account id. |
Integration username | Auto‑provisioned service user shown next to the key. Your token inherits its roles and rights — you don't choose the name. |
The API is deployed regionally; your base URL follows https://<region>.focus.subphonic.ai/api (e.g. uk, eu, us, ca). See Base URLs and environments for the full list.
Endpoint reference
Browse the interactive, always‑current reference for every documented call. Each page lists the full request and response schema and lets you call the real API from your browser.
| Group | Endpoints |
|---|---|
| Auth | Authenticate with API key |
| Recording | Search recordings · Get recording detail · Get transcriptions · Get SMS message bodies · Download recording media · Get recording audit log |
| People and Endpoints | Get people by id · Search people · Search people by name · Get endpoints by value · Search endpoints |
| User | Search users |
| RetentionGroups | List retention groups |
| Comment | Get comments on a recording |