Poll the CDR endpoint for reporting and billing. Ask us about webhooks when you need something to happen the instant a call arrives.
Every business phone system keeps a record of every call: who rang, who answered, when, from what number, and for how long. Most South African businesses never look at it beyond the occasional glance at a dashboard, which is a shame, because it is usually the most complete record a company has of its own customer contact.
If your phone system has an API, that record is not stuck in a portal. Here is what is actually available on Othos, what businesses genuinely build with it, and what it costs — including the parts it does not do.
What the Othos API actually gives you
The public API is a REST interface to your Call Detail Records. It is documented, live, and you can read the specification before committing to anything: the CDR API documentation is public.
Authentication. You authenticate with an API key issued to your account, exchange it for a JWT token, and use that token as a bearer credential. Tokens last 30 minutes, so anything long-running refreshes as it goes.
Scoping. Each API key is tied to a specific domain and returns CDR data only for that domain. You cannot accidentally read somebody else’s call records, and neither can anyone else read yours.
Querying. You request a date range and get JSON back. You can narrow it by time of day, by partial caller number or partial destination number, and page through results — up to 1,000 records per request, with an offset for pagination. There is also a download endpoint for bulk extraction and a health endpoint for monitoring.
What is public, and what you ask for
The CDR API above is public and self-serve: the documentation is online, and if you have an API key you can pull your first day of records this afternoon without speaking to anybody.
Real-time webhooks exist as well. Call events can be pushed to your endpoint as they happen, which is what you need for a screen pop, a live wallboard, or a workflow that reacts the moment a call arrives. We do not publish that documentation publicly, for security reasons — it comes from us on request rather than off a web page.
The practical split is straightforward. If you want reporting, billing, reconciliation or activity tracking, poll the CDR endpoint on a schedule and you are finished. If you need something to happen the instant a call starts or ends, ask us about webhooks.
What businesses actually build with call data
Client billing and reconciliation. Law firms, agencies and consultancies that bill for time spent on the phone can pull the CDR for a period, match calls to clients by number, and generate billing lines without anyone transcribing a call log by hand. This is the single most common reason customers ask us for API access.
Reporting in the tools you already use. Pull CDR into Power BI, Looker Studio or even a scheduled Google Sheet, and you can report on call volumes, answer rates and busy periods next to your sales and revenue numbers rather than in a separate portal. Most operations teams would rather have one dashboard than two.
Missed-call and abandoned-call alerting. A scheduled job that pulls the last hour of records and flags inbound calls that went unanswered turns a silent revenue leak into a task in somebody’s inbox. Businesses are usually surprised by the number.
Sales activity tracking without a CRM. Not every company runs a CRM, but most want to know who is actually making calls and how many. The CDR answers that directly, per extension, without buying anything else.
Service-level monitoring. If you have committed to answering within a certain time or returning calls the same day, the call record is the evidence. Pull it, measure it, and stop arguing about it.
Feeding a warehouse. For companies that centralise data, the download endpoint makes call records just another nightly extract alongside everything else.
When and where?
Plenty of what people ask the API for is already built. Othos has working integrations, in production with real customers, for HubSpot, Salesforce, Zoho CRM and Zoho Bigin, SmartCRM, and Google Workspace. Microsoft Teams is also supported.
If your CRM is on that list, you do not need a developer. If it is not, the API is there, and beyond that we quote custom integrations per project — a genuine option rather than a polite deflection, because we develop the platform ourselves rather than reselling somebody else’s.
What it costs
Straightforwardly: using the API yourself is free. If your team or your developer builds the integration, there is no charge for API access, on any plan.
If you would rather we build and manage it for you, that is a managed service from R399 a month depending on scope, and it is included on the Enterprise plan. Larger custom integration work is quoted per project.
We would rather put that in writing than have you find it at the quoting stage.
How to get started
Ask for an API key. Keys are issued per domain by your account administrator.
Read the documentation. It is public, and short enough to read in one sitting before you decide whether this is worth anyone’s time.
Pull one day of records. Authenticate, request yesterday, and look at what comes back. You will know within an hour whether it answers the question you have.
Then automate the boring part — the scheduled pull, the reconciliation, the alert — rather than building a platform you do not need.
Frequently asked questions
Do I need a developer to use the phone system API?
For the native integrations, no — those are configured, not coded. For the CDR API you need someone comfortable making an authenticated HTTP request and handling JSON. That is a competent analyst with Python or a low-code tool, not necessarily a software team.
Which CRMs does Othos integrate with?
HubSpot, Salesforce, Zoho CRM, Zoho Bigin, SmartCRM and Google Workspace are live with real customers. Microsoft Teams is supported for dialling. Anything else is either an API build or a custom project.
Can I get call events in real time?
Yes. Webhooks push call events as they happen, which covers screen pops, live wallboards and event-driven automation. That documentation is not published publicly for security reasons — ask us and we will provide it.
How far back can I pull call records?
You query by date range, so it depends on your retention. Recordings are retained for as long as you are a client, and call records are queryable across that history.
Is the API secure?
Access is via a JWT obtained from a UUID API key, and every key is scoped to a single domain, so a key can only ever return that customer’s records. Tokens expire after 30 minutes.
What does the API cost?
Nothing, if you build it yourself — API access is free on every plan. If you want us to build and manage the integration for you, that is from R299 a month depending on scope, and included on Enterprise. Larger custom projects are quoted individually.
The bottom line
Your call records are a genuinely useful dataset that most businesses leave sitting in a portal. The API to get at them is documented, scoped to your own data, and simple enough that a competent analyst can pull a useful answer out of it in an afternoon.
The public CDR API covers reporting and billing without anyone needing to talk to us, and webhooks are there for when you need to react in real time. If what you need goes beyond both, we develop the platform ourselves, so custom work is a real conversation. See our CRM integrations → or talk to us about an integration →.
