Getting started

Check GET /v1/capabilities before enabling a workflow. Features depend on estate configuration and token scope. A production API changes live accounts, billing and telephony; a hostname does not imply that data is a disposable sandbox.

1. Obtain an estate token

An administrator manages API access in the estate's CallPlatform portal. Choose an active administrator as token owner, grant the minimum scopes, set an expiry and restrict source IPs where practical. Copy the token when created: only its hash is stored, so it cannot be displayed again. Revoke or rotate it through the same workspace.

Scopes cover accounts, users, numbers and services (:read and :write), reports (reports:read), media (media:read) and conference control (conferences:write). A token's scopes cannot override its owner's disabled, deleted, unverified or view-only state.

Keep a partner token on your application's server. Do not embed it in a distributed browser/mobile application or commit it to source control. This release provides estate API tokens, not OAuth or public-client sign-in.

2. Discover the deployment

Set BASE to this deployment and obtain TOKEN from your secret manager or shell environment.

Requests and responses use JSON. An account filter or resource ID outside the verified hierarchy returns 404. Missing or inactive credentials return 401; a missing scope returns 403. Errors use {"error":{"code":"...","message":"..."}}.

3. Read calls and media

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/reports/calls?direction=inbound&per_page=25"
curl -H "Authorization: Bearer $TOKEN" "$BASE/reports/summary"
curl -H "Authorization: Bearer $TOKEN" "$BASE/media/recordings"
curl -H "Authorization: Bearer $TOKEN" "$BASE/media/audio"

Report and recording dates are inclusive UTC days, with a seven-day default and a 31-day maximum. Call reports accept literal caller/destination filters. meta.has_more indicates another page; these are live pages, not a stable export snapshot. No raw CDR JSON, platform cost or arbitrary SQL is exposed.

A recording detail includes its transcript and summary when available. Filter recordings by the report's exact URL-encoded call_id and explicit dates. Recording dates are metadata creation dates: processing can finish after the call day. Zero or multiple recording, voicemail or conference segments may match.

Obtain a five-minute URL with GET /media/recordings/{recording_id}/download?disposition=inline or GET /media/audio/{audio_id}/download?disposition=inline, then pass the returned URL directly to your audio player, without the API bearer header. Omit disposition for a normal attachment download. The response includes MIME type and byte size. Treat signed URLs as temporary credentials: never log or persist them; renew after expiry. Missing/empty objects return 404, unprocessed/archived media 409, and storage or configuration failures 503. Upload and processing remain in the portal.

Read numbers with GET /numbers (optional literal search) and GET /numbers/{number_id}. Prices reflect the current recurring rental; missing/ambiguous prices are null. The legacy available-inventory response is not a purchase quote. Approved partners use the number-ordering flow below.

4. Make a supported service change

Read the service first and check its supported_updates. Preserve its config_hash and send it as a quoted If-Match value when updating, deleting or attaching a number. This guards against a portal or API edit made since your read.

curl -H "Authorization: Bearer $TOKEN" "$BASE/services/$SERVICE_ID"
# Review the response, then set CONFIG_HASH to its data.config_hash.
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H "If-Match: \"$CONFIG_HASH\"" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -d '{"account_id":2,"name":"Support line"}' "$BASE/services/$SERVICE_ID"

A missing precondition returns 428; stale configuration returns 412. Re-read and review before submitting a new change. The friendly configuration summary is read-only; do not PATCH a whole GET response. Rich section replacement and portal-format Flow graphs are not supported. The API reports supported updates explicitly.

Use a fresh UUID idempotency key for each intended mutation; reuse that key only when retrying the same payload and reviewed precondition. Account-owned number/service mutations also require the exact account_id. When separately enabled, scheduled number cancellation records the portal's 30-day notice and applicable WhatsApp removal intent. It preserves existing quarantine/reuse holds; the estate job owns later teardown and reuse eligibility. This request does not detach routing. Immediate cancellation is unavailable.

User passwords require 12–72 characters and at most 72 UTF-8 bytes, with no NUL bytes. Where user_invitations is available, use send_invite:true to invite an ordinary user instead. Password or phone changes revoke remembered portal credentials; a phone change also disables SMS MFA until re-enrolled. Administrator users and custom permission grants remain portal-managed.

5. Build your own signup and provisioning flow

Partner provisioning is enabled separately for the account that owns your integration token. An approved partner can manage its permitted child accounts; the children do not gain independent provisioning access. Keep the token and all API requests on your application server.

1. Read GET /accounts/options?account_id=YOUR_ACCOUNT. Create the customer with POST /accounts, using that parent, the chosen published rate plan or parent-rate copy, country, timezone, payment type and contact details. Send a UUID Idempotency-Key. The response identifies the new account and any welcome-email result.
2. Create an ordinary portal user with POST /users if the customer needs one. Your own website can retain its own sign-in system.
3. Search both sources with GET /number-orders/search?account_id=CUSTOMER_ACCOUNT&prefix=0191&source=all. Each candidate includes account-priced setup and monthly amounts, source, an opaque quote and expiry. Supplier stock depends on deployment support.
4. Refresh the chosen quote with POST /number-orders/quote and a JSON body containing account_id and quote. Show the returned price to your customer.
5. Order with POST /number-orders, the same two body fields and a new UUID Idempotency-Key. Keep that UUID and exact quote for every retry. Read GET /number-orders/UUID?account_id=CUSTOMER_ACCOUNT for status. Pending or review is not a failed purchase: never submit a second order to work around it.
6. Once completed, create a supported service and attach the returned number_id using the service's current revision. Read calls through /reports/calls and /reports/summary.

Amounts are integer minor currency units. Prepay orders debit setup plus the first monthly rental once; postpay orders create the normal billing records. A new number is unassigned until you attach it to a service. Immediate release and account billing-setting changes are outside this partner release.

6. Control an existing conference

An explicitly granted conferences:write integration can use the conference action endpoint when its estate runtime and caller gates are ready. This grant is independent of partner provisioning approval. The global read-only guard and current token-owner restrictions still apply. Supply a verified live channel UUID, safe room token and UUID idempotency key; the server checks room and targeted membership before acting. Room moves, transfers, call discovery and conference events are unsupported.

Endpoint catalogue

Generated from the same OpenAPI contract used by the reference, Postman collection and request testers.