Use the current API reference
Open API documentation while signed in. The reference contains supported endpoints, required fields and examples. Use it as the source for request details; this guide explains the workflow rather than duplicating the endpoint specification.
Prepare your key
Follow the identity verification prompt to view or copy your key. The documentation allows a five-minute verified window for viewing the key and using the Playground; generating or regenerating a key requires verification again. Treat the key like a password: keep it on your application's server, out of public repositories, browser code and screenshots.
Make a safe first request
- Open the Playground and select a read-only preset appropriate to your account, such as listing SIP identities.
- Review the method, path and parameters. Use identifiers returned for your own account rather than example values.
- Choose Run request and inspect both the HTTP status and response body.
- Use the documented request example in your application with secure credential storage.
The Playground uses your account. Requests that send messages, place calls or order services can perform real actions and incur charges. Do not treat it as a free sandbox.
Add webhook notifications
In account integrations, add an HTTPS endpoint and select the events you need. The webhook signing secret is separate from your API key. Verify signatures, process each event once and acknowledge receipt promptly. Check delivery logs when troubleshooting. Consult the API's retry and duplicate-request guidance before retrying a paid operation; a timeout alone does not prove it failed.
Related guides
Choose the right service reference
The reference separates Lookup, Pricing, SIP, SMS, Contacts, Speech API, Phone Numbers, Voice API and Calls & recordings. Use the endpoint documentation for the exact prerequisites, request fields and charges. Browser calling has its own Webphone SDK guide; it is not the same as server-side Voice API call control.
An agent’s permission to read API documentation does not grant access to the account owner’s API key or key-authenticated Playground execution. Ask the account owner to manage integration credentials rather than sharing their login.
Use returned references and pagination
Treat public call references as opaque values: copy the complete CALL- reference from your own response instead of constructing one or using an internal telephone-system identifier. Historical calls and active calls are different lists. A control action also needs a call in the supported state; an old history row is not necessarily controllable.
For call-history pages, follow pagination.next_cursor while pagination.has_more is true. Keep the original days, limit and SIP identity filters unchanged. Do not decode or modify the cursor. If it expires, start a new listing and reconcile by public call reference. An API timestamp documented as UTC must be converted intentionally for your display; it is not automatically your browser’s local time.
Handle errors without duplicate paid actions
Read the HTTP status and structured error together. Correct validation or authorization errors before retrying. Respect the documented retry delay for a rate limit. For a timeout or temporary error on a paid action, check its status and the endpoint’s duplicate-request rules before submitting again; changing request identifiers can turn a retry into a new operation. Keep the public request/reference, time and sanitized error for Support, never the API key.