Native Focus REST API
Overview
The Native Focus REST API is the primary programmatic interface to your Focus tenant. It exposes the same data the Focus portal uses — communications (recordings, calls, SMS, Teams interactions), people, endpoints, users, retention groups, comments and tags — through a JSON HTTP interface protected by a short‑lived bearer token.
This API is intended for back‑office, server‑to‑server integrations such as:
- Indexing recording metadata into a downstream warehouse, eDiscovery or surveillance platform.
- Pulling audio, video or transcripts on demand for QA and compliance review.
- Reconciling people, endpoints and retention assignments against an upstream system of record.
- Driving custom reporting or dashboards over your communications data.
The endpoints described in this section are deliberately limited to read / search operations that are safe to integrate against without risk of changing portal data. Write, update and delete endpoints exist on the API but are reserved for first‑party Focus tooling and are not documented publicly. If you have a use case that needs a write operation, please contact support.
This section is the hand‑crafted guide — it teaches the end‑to‑end flow with worked curl examples. For the auto‑generated OpenAPI reference — every field typed, plus an interactive "Try it" console for each call — see the Focus API reference. The two are kept in step and link to each other; use the guide to learn the flow and the reference for exact schemas and live testing.
Before you start
- Enable the API on your account from Admin → Account → Integrations. A Super User must turn the API on and generate an API key.
- Note your
clientId— this is your Focus account identifier. It is shown alongside the API key in the admin section. - Use the integration username supplied with your API key — when the API is enabled, Focus automatically provisions a dedicated service user and shows its username next to the key. Calls authenticate as that user and inherit its roles and rights. You don't choose your own username.
- Pick the right base URL for your region — see Base URLs.
What's in this section
| Page | Use it for |
|---|---|
| Getting Started | Quickstart with curl: prereqs, base URLs, authentication, end‑to‑end "find a call and download the audio" walkthrough, pagination, errors and rate limits. |
| Endpoint Reference | Per‑endpoint reference grouped by resource (Auth, Recordings, People & Endpoints, Users, Retention Groups, Comments, Audit) with request shapes and example responses. |
| Focus API (OpenAPI reference) | Auto‑generated, always‑current schema for every endpoint, with an interactive "Try it" console. Use it alongside this guide for exact field types and live testing. |
Capability matrix
The table below summarises the read capabilities exposed by this documentation. Roles and rights are enforced server‑side; if your service user lacks the required right the call returns 403. Each capability links to its OpenAPI reference page, where you can see the full schema and try the call live.
| Capability | Endpoint | Required right (typical) |
|---|---|---|
| Authenticate with API key | POST /authWithApiKey | — |
| Search & filter recordings | POST /client/recording.search | Recording.View |
| Retrieve recording detail | POST /client/recording.detail.get | Recording.View |
| Retrieve transcription | POST /client/recording.transcription.get | Recording.Transcription.View |
| Retrieve SMS message body | POST /client/recording.sms-message.get | Recording.View |
| Stream / download audio | POST /client/recording.playBackByThirdPartyId | Recording.Play |
| Read recording access audit | POST /client/recording/audit | Recording.Audit.View |
| Search people | POST /client/people.search, POST /client/people.searchByName | People.View |
| Get people by id | POST /client/people.get | People.View |
| Search endpoints | POST /client/people/endpoint/search | Endpoints.View |
| Get endpoints by value | POST /client/people/endpoint/get | People.View |
| Search users | POST /client/user/search | Users.View |
| List retention groups | GET /admin/retentionGroup | RetentionGroup.View |
| Get comments on a recording | GET /client/recording/comment | Recording.Comment.View |
Conventions used in this documentation
- All examples use
{{baseUrl}}as a placeholder for your tenant's API host. Substitute the value supplied by your account manager. - All authenticated requests require an
Authorization: Bearer <token>header. Tokens come fromPOST /authWithApiKey(see Getting Started). - All request and response bodies are
application/jsonunless explicitly noted (audio download returns a binary stream). - Identifiers come in two flavours: the internal
interactionId/recordingId(numeric, stable within Focus) and thethirdPartyId(string, supplied by the source platform — e.g. a Teams call id). Most search results expose both; audio download is keyed onthirdPartyId.
Related integrations
- Cursor Synchronisation — pull‑model alternative for bulk metadata sync.
- Push API — event-driven transcript completion notifications for low-volume customers.
- SFTP — legacy bulk audio/metadata delivery.
- SMS & Email — outbound notification integration.
- NICE — packaged export to NICE platforms.