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.
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. |
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.
| Capability | Endpoints | 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.