REST API Reference
Learn more about our Voice API, Join our Discord community - we're here to help.
Please note that this part of the documentation is being replaced by the API Playground. This section will remain available for remote linkage purposes.
Throughout our documentation, the terms tenant and customer are used interchangeably - these are identical. We are working towards migrating all occurrences of the tenant term to customer, so please take this into account as you go through our documents.
Introduction
Cloudonix's Voice API provides the developer easy access to making calls, manipulating call flows, integrating with 3rd party systems and more.
Using this Voice API, you can initiate outgoing calls, control and manipulate calls in progress, query current and past calls and more. By combining Cloudonix's Voice API and Cloudonix Markup Language (CXML), you can create highly interactive voice applications, such as IVRs, AI Voice Agents, surveys, and more.
In addition to the above, the Voice API also enabled control over various assets related to your Cloudonix account.
We are firm belivers in "Eating our own dog food" - which means, that we use the same APIs to drive our cockpit. Most Cloudonix customers use the Voice API for all platform related operations, completely bypassing the cockpit.
Rate Limiting
Rate limiting in the Cloudonix Voice API is designed to control the number of requests a client can make to the API
endpoint within a specified time frame, from a single domain. This mechanism helps to prevent abuse and ensures fair
usage of resources, maintaining the stability and performance of the API for all users. Exceeding the rate limit will
result in the server temporarily rejecting further requests until the rate limit window resets.
| Number of requests | Resources | Time Window | Error code on exceeding threshold |
|---|---|---|---|
| 10 | Per Domain | 10 seconds | HTTP 429 |
To acheive higher performance, you may use multiple domains or contact support to increase your customer domain rate limiter.
Authenticate vs. Authorize
Cloudonix maintains a strong distinction between Authenticated Users and Authorized Resources. Pay attention to the distinction between these, as using these in a wrong fashion may result is your applications' exposure to security issues, illegal usage or other undesired results.
Authenticated Users
Authenticated Users are registered using the Users API and are authenticated by the Cloudonix Dashboard through an OAuth 2.0 secure authentication workflow. Currently, Cloudonix only supports Google OpenID Connect provider, with additional implementations to follow. Users can be limited to specific Cloudonix Domains, or may have access to all customer tenant administrative operations and all resources of the customer/tenant.
Authorized Resources
Authorized Resources are programmable resources, identified using an API key. Cloudonix maintains 5 different levels of API keys, each providing your programmable resource with different levels of access. These include the following: Customer/Tenant API Key, Domain API Key, Voice Application API Key, Subscriber API Key and User API Key.
User API Key
When creating your Cloudonix account, you will automatically be provisioned with a User API Key, which will be presented to you in the cockpit interface. Login to your Cloudonix account, and select Settings from the left menu, then click the API Keys tab, the following view will appear:
Your first user is your customer owner user, and has an Administrator level API key. Pay attention that the key designated as Your personal API key and the key in the list below are identical.
Depending on your user level access (Customer/Tenant or Domain), your API key will have identical access rights.
Customer API Key
Customer/Tenant API keys have full access to all customer/tenant owned resources. Using a customer/tenant API key grants full read/write access writes to all account resources.
It is not advised to use Customer/Tenant API keys for your applications - these are provided for management purposes.
Domain API Key
Domain API keys have full access to all domain related resources. While a single customer/tenant may have multiple domains, a domain API key has access to a single domain only.
Voice Application API Key
A Voice Application API key enables control over the voice application itself, or other information stored in relation to the voice application itself, such as the voice application profile, subscriber related information, etc. A voice application API key can not affect other resources in the domain.
Subscriber API Key
A Voice Application API key enables control over the subscriber itself, or other information stored in relation to the subscriber, such as the subscriber profile. A subscriber API key, very much like a voice application API key, cannot affect other resources in the domain. The subscriber API key can be used to initiate voice calls, send messages via the messaging API and more.
More details can be found in: Authorization & Authentication REST API