API Access

What the API does

Everything you do in the partner dashboard, you can do via the API. Common uses:

• CRM integration — auto-create tenants when a deal closes in HubSpot/Salesforce
• Provisioning automation — bulk-create extensions from a CSV when a customer onboards
• Billing integration — pull invoices into your accounting system on a schedule
• Customer self-service — let tenants do specific actions in your branded app, not in our dashboard
• White-labeling — build your own dashboard on top of our API and never expose ours

Where the docs live

The full API reference, with request/response examples for every endpoint, is at:

https://api.simuwave.com

That same hostname serves both the interactive documentation (at the root path) and the API itself (at /v1/*). The docs page has the full OpenAPI spec, search across every endpoint, and a try-it-out feature where you can test calls against your account from the browser.

This chapter doesn't duplicate the API reference. It tells you how to get access to the API and the high-level shape of what's available.

Creating an API key

Top nav → Settings → API Keys. Click Create API Key.

The form:

• Name — for your own reference, e.g., "Production CRM Integration"
• Scopes — which categories of endpoints this key can hit. Checkboxes grouped by resource: Tenants, Phone Numbers, Extensions, Call Flows, Queues, Voicemail, Calls, Billing, Webhooks, Provisioning. Use Select All during initial setup if you want a key that can do everything.
• Tenant Scope — leave blank for a partner-level key (full access across all your tenants). Or select specific tenants to restrict the key to those tenants only. Useful if you want to give a third-party developer access to one tenant without exposing the rest.
• Rate Limit — requests per minute. Default 100, max 10,000. The platform enforces this; over-rate requests get HTTP 429.

Click Create Key.

The plaintext key is shown exactly once. Copy it immediately and store it somewhere safe (your secrets manager, your CI environment, your .env file). After you close the modal, only a masked version of the key is visible. We can't recover lost keys — you'd have to revoke the old one and create a new one.

API base URL

https://api.simuwave.com/v1

(Or https://api.simuwave.com/v1 regardless of your custom domain — the API isn't currently served from custom domains.)

Authenticating

Every request uses bearer authentication. Include your key in the Authorization header:

Authorization: Bearer sk_live_abc123def456...

Example with curl:

curl https://api.simuwave.com/v1/tenants \
  -H "Authorization: Bearer sk_live_abc123def456..."

If your key is invalid, expired, or revoked, you'll get a 401 Unauthorized. If it doesn't have permission for the resource, you'll get 403 Forbidden.

What's available

The API mirrors the dashboard. High-level groups:

Group	Sample endpoints
Tenants	Create, list, update, suspend, unsuspend, get usage
Extensions	Create, list, update, delete, reset password
Phone Numbers	Search inventory, list assigned, assign to tenant, release, set CNAM, register E911
Call Flows	Create, list, update, attach DIDs, detach DIDs
Queues / Ring Groups / Voicemail	Standard CRUD
Calls (CDR)	List call records, get a specific call's metadata + recording URL
Billing	List invoices, get invoice detail, create checkout session, manage subscription
Faxes	Send, list inbox, list sent, get document
Port Requests	Create, list, cancel
Webhooks	Manage your webhook endpoints (covered in chapter 16)

Full method list, request/response shapes, and error codes are at api.simuwave.com.

Managing keys

The API Keys table shows every key:

• Name
• Key (masked: sk_live_...abc1)
• Scopes count
• Tenant Scope (badge: "All tenants" or count of restricted tenants)
• Status (ACTIVE / REVOKED / EXPIRED)
• Last Used (timestamp or "Never")
• Actions

You can:

• Edit — change scopes and tenant scope (you can't change the key value or name)
• Revoke — disable the key. Existing requests using it will start returning 401 within ~60 seconds (cache TTL).

Best practices

• One key per integration. If you have a CRM integration, an accounting integration, and a tenant self-service app, that's three keys. Easier to revoke one without breaking the others.
• Scope down. Only grant the scopes the integration actually needs. A key that only reads invoices doesn't need write access to extensions.
• Restrict to specific tenants when handing keys to third parties.
• Rotate keys quarterly as a hygiene practice. Create a new one, switch your integration over, revoke the old.
• Monitor Last Used. A key showing "Never" for months is probably orphaned and should be revoked. A key suddenly going from "minutes ago" to "hours ago" might mean an integration broke.
• Never put keys in client-side code, public repos, or chat logs. If you accidentally leak a key, revoke it immediately, then audit the API request log (in our Audit Log) for any unexpected calls.

Rate limits

The platform-wide limit is 1000 requests/minute per partner across all keys. Per-key limits (set when you create the key) cap individual key usage. Hit either and you get HTTP 429 with a Retry-After header indicating when to retry.

Most integrations don't get anywhere near these limits. If you have a use case that requires sustained high request rates (e.g., real-time call analytics), open a support ticket and we'll discuss options.

SDKs

Currently no official client libraries. The API is straightforward REST + JSON; community-maintained wrappers exist in Python, Node.js, and Ruby — search GitHub for "simuwave api" or generate one yourself from the OpenAPI spec at api.simuwave.com.

Webhooks vs polling

For events you want to react to (a tenant signed up, a call ended, a payment succeeded), use webhooks (chapter 16). For periodic data syncs (e.g., pull yesterday's invoices into your accounting system), use polling.

Don't poll the API every few seconds for events — your rate limit will run out and you'll get inconsistent latency. Webhooks are real-time and free.