Cloud9 APIs and API rate limits

Cloud9 provides a comprehensive suite of standardized APIs designed to streamline integration with third-party applications and services. These APIs offer flexibility and control, enabling clients to build tailored solutions that enhance their workflows and extend the capabilities of the Cloud9 platform.

• Available APIs
• API rate limits
• HAMAC generation
• HMAC signature and digest construction

Available APIs

Call Data API

Enables retrieval of call metadata, audio recordings, and transcription files stored in AWS cloud storage. The API also supports sending this data to integrated third-party value-added services for further processing or archival.

Monitoring API

Provides API-level access to most Cloud9 Portal functions, including the ability to view, add, edit, and delete users, buttons, connections, and groups.

Management API

Exposes user activity logs, audit trails, and trader/system-level alerts from the Cloud9 Admin Portal via API endpoints, allowing for centralized monitoring and compliance reporting.

Recording Systems API

Allows access to call metadata and audio recordings for customers using on-premises voice storage systems. The API is compatible with most major voice recording solutions.

CTI API (Computer Telephony Interface)

Enables server-side applications to control the Cloud9 application. This includes receiving real-time event data and placing calls on behalf of users, ideal for middleware integration and workflow automation.

API rate limits

Below is a summary of the current rate limits for each supported API. These limits are enforced to ensure optimal system performance and fair usage across all clients.

Call Data API rate limits

Management API rate limits

Monitoring API rate limits

HMAC generation

This section provides descriptions and code examples of how to construct the HMAC Digest that is required to make an authenticated request to the Cloud9 APIs.

Every request to an API endpoint must be authenticated. Authentication is verified by Cloud9 through the customer providing an HMAC SHA512 signature that is generated with a public and private key created through the Cloud9 Admin Portal.

The following description and code examples call for an HMAC SHA512 hash to be generated. This is not interchangeable with a SHA512 hash and submitting a SHA512 hash as the authentication to a request will cause it to be rejected. HMAC SHA512 is a well-defined standard for which Cloud9 never used custom libraries. Each code example in the following section details what standard library for the specified language is being used to generate the HMAC SHA512 hash.

All requests to REST endpoints must include an HMAC SHA512 authentication signature generated over the entirety of the request (headers and body) where the HMAC algorithm is salted with the secret key. This step allows Cloud9 to verify that the request has not been tampered with in transit.

The public key must be provided in every request allowing Cloud9 to verify the IP whitelist associated with the key against the source of the incoming request and that the key is valid and unexpired.

HMAC signature

The Signature is an HMAC SHA512 hash of the entire contents of the request, including headers and body of the message. To generate the HMAC signature, you can use any standard HMAC SHA512 library in your preferred language. The API secret is used to seed the HMAC SHA512 hashing algorithm. The API key, along with the entire contents of the request (including headers and body) are combined into a string which is passed into the hashing algorithm. The resulting HMAC signature is provided in the Authentication header of the request and used by Cloud9 to verify that the customer's request is authentic and authorized.

HMAC digest

The Digest is composed of four separate pieces: a prefix, the public API key used in the generation of the Signature, a globally unique identifier (guid), and the Signature.

The purpose of the Digest is for Cloud9 to verify both the authenticity and integrity of the request from a customer. To verify authenticity, Cloud9 compares the API public key against the key generated by the customer through the Cloud9 Portal. To verify message integrity, Cloud9 compares the Signature against a hash created on the received message with the customer’s public and private keys using the same methodology described on this page.

HMAC signature and digest construction

The HMAC Signature is generated on the entirety of the request that will be sent to Cloud9, including all headers and the body of the request. To generate the HMAC Signature, the entire request should be provided in string format into your chosen HMAC library in the order specified as follows:

1. request type (ex. ‘POST’)
2. delimiter (ex. ‘\n’)
3. ‘https’
4. delimiter
5. API URI and port (ex. ‘calldataapi.xhoot.com:443’)
6. delimiter
7. API endpoint (ex. ‘/v1/calls/metadata’)
8. delimiter
9. Content-Type (ex. ‘application/json’)
10. delimiter
11. API public key
12. delimiter
13. nonce (guid)
14. delimiter
15. request timestamp (ex. ‘Thu, 3 Dec 2019 05:27:23 GMT’)
16. delimiter
17. request body
18. delimiter

Example of full input string for HMAC SHA512 hashing

'POST\nhttps\ncalldataapi.xhoot.com:443\n/v1/calls/metadata\napplication/json\n' + api_public_key + '\n' + nonce + '\nThu, 23 Apr 2020 17:45:11 GMT\n{"beginDate": "2025-06-27 20:19:00","endDate": "2025-06-27 21:51:00","pageSize": 1000}\n'

Important considerations

• Ensure that the timestamp is generated once for both the hash and the message.
• Ensure the nonce is generated once and reused in both the Signature and the Digest.
• Ensure that the request body is identical in structure and formatting.
• Always provide a request body, even if empty, for all requests to avoid signature mismatches.
• Do not reuse HMAC Signatures across different requests. Each request must have a unique signature.

Final HMAC Digest format (to be used in the Authorization header)

HmacSHA512 ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6VXhNaUo5LmV5SnpkV0lpT2lKRFlXeHNjeU JFWVhSaElpd2lZWFZrSWpvaU1UTWlMQ0poY0dsRmJuWWlPaUpRVWs5RUlpd2libUptSWpveE5U Z3dPRFl3T0RBd0xDSmhjR2xXWlhKemFXOXVJam9pTVM0d0xrZEJJaXdpYVhOeklqb2lZemtpTE NKbGVIQWlPakUyTVRJek9UWTRNREFzSW1saGRDSTZNVFU0TURreE1UazBObjAuRFNaTG9TU09a dzR0QUJEUnMzbWZ1QUVIRGZCRFNTR0xLbmJfUDRnTjFTZ0c2S09RdzlDcWZvdmxDNWlqbkoyM1 p3Q1lWTDNtYmNiOTBjRmFadURTbFE=:4b426367-7c46-4554-b4a7 dff043526862:Ldf+UUVyXf0moAz6quG5/KEHq2qLUSbczursglLa/on0ZTkgD3LQdtFJgWgG6 9MICOMJ/6fzbV2nh5Li/AK19w==

As previously mentioned, it is important that the nonce provided in the digest is the same nonce that was used in the Signature.

If a Digest is incorrectly formatted, the expected response is an HTTP 401. If a Signature does not match, the expected response is an HTTP 403. Cloud9 cannot determine the specific nature of what may be causing an invalid Digest or Signature. Under no circumstances should the API secret be transmitted to Cloud9 in any request.

For further assistance with API usage, rate limit adjustments, or integration guidance, please contact Cloud9 Technical Support - C9Helpdesk@symphony.com.