Contactivity API reference

The Contactivity API places and controls calls, manages numbers, trunks and voice apps, and reports usage. It is JSON over HTTPS, one project per path:

https://api.contactivity.io/v1/projects/{project_id}/...

The interactive reference is the API Reference tab; the spec is /openapi/native.yaml (OpenAPI 3.1). The SDKs are @contactivity/sdk (Node) and contactivity_sdk (Python). Moving from Twilio or Telnyx? See Compatibility API.

Region

Send requests to your project's region: https://api.<region>.contactivity.io (for example api.us1.contactivity.io); https://api.contactivity.io is us1. A key from another region is refused with 401 and a body naming the right host.

Authentication

Create an API key in the portal (Settings > API keys) and send its secret as a bearer token:

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/calls \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY"

A key belongs to one project. {project_id} must be that project, or the answer is 404 not_found ("Project not found"). A bad or revoked key gets 401 authentication.

Scopes

A key carries scopes. Each endpoint needs the scopes listed on its page (and in the spec's x-scopes); a key without them gets 403 insufficient_scope and a message naming the missing scope.

API keys cannot create keys, top up or change payment methods; those stay in the portal.

Requests and responses

• Bodies are JSON (Content-Type: application/json) with snake_case fields. Bodies are strict: an unknown field is 400 unknown_parameter (with param), a field of the wrong type is 400 invalid_parameter.
• POST that creates returns 201 and the object; DELETE returns 204 with no body; reads and updates return 200 and the object.
• DELETE archives; nothing is deleted (see Archiving). The one exception is a phone number: DELETE /numbers/{phone_number} releases it.
• Timestamps are RFC 3339 UTC with milliseconds: 2026-10-22T14:03:11.123Z.
• Durations are whole seconds, in fields ending in _secs.
• Money is an object: {"amount": "0.0130", "currency": "USD"}. amount is a decimal string and never negative (4 decimals for usage, 2 for balances); a ledger entry says credit or debit in direction.
• IDs are opaque strings: CA… calls, RE… recordings, TR… transcriptions, CF… conferences, QU… queues, app_… voice apps, trk_… trunks, rt_… routes, byoc_… BYOC carriers. Phone numbers are E.164 and are URL-encoded in paths (/numbers/%2B14155551234).
• Every response carries X-Request-Id (req_…). Quote it when you contact support.

Errors

Every error has the same body:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "to must be an E.164 number, client:<name> or a SIP URI with a public host",
    "param": "to",
    "request_id": "req_us1_…",
    "doc_url": "https://docs.contactivity.io/errors/invalid_parameter"
  }
}

Branch on code, not on message. param names the field, query parameter or header at fault, when there is one. Codes every endpoint can return:

Endpoint pages list the other codes they return (for example call_state, insufficient_balance, caller_id_not_verified, number_not_available).

Pagination

Lists return a page, newest first:

{"data": [ ... ], "has_more": true, "next_cursor": "<opaque cursor>"}

Pass limit (1-200, default 50) and, for the next page, starting_after=<next_cursor>:

curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/calls?limit=100&starting_after=$CURSOR" \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY"

A few small lists (conference participants, queue members, verified numbers, trunk credentials and IPs, available numbers, catalogs such as voices) are a single page: has_more is always false. Their pages say so. The SDKs' iterate() follows next_cursor for you.

Archiving

Nothing you create is deleted. DELETE on a resource archives it and still returns 204:

• It stops working at once: an archived API key cannot authenticate, a SIP credential or trunk IP cannot register or authenticate, a route no longer routes, a voice app, PBX app or flow is handled like a missing one, an alert rule stops firing, a caller ID cannot be used, a queue refuses new callers.
• Lists leave it out. Add ?archived=true to a list to get only archived resources.
• GET by id still returns it, with archived_at set (an RFC 3339 timestamp; null while active).
• Changing it, or a second DELETE, is 409 archived. Archiving is permanent: there is no restore.

Call data is never erased: calls, recordings and their audio, transcriptions, voicemail, and events. The one exception to archiving is a phone number: DELETE /numbers/{phone_number} releases it. The Twilio- and Telnyx-compatible APIs archive in the same way (an archived resource answers 404 there and leaves their lists); deleting an IncomingPhoneNumbers entry still releases the number.

Project retention settings (retention in /v1/projects/{id}/compliance) no longer remove anything: PUT accepts them and changes nothing, and GET returns every retention value as null (data kept).

Idempotency

Send Idempotency-Key: <8-100 characters> (a UUID is fine) on any POST. For 24 hours, the same key with the same method, path and body returns the first response again, with Idempotent-Replayed: true, instead of acting twice. So a POST that timed out can be retried safely with the same key.

• The same key with a different request: 409 idempotency_conflict.
• The first request is still running: 409 request_in_progress; retry shortly.
• With the header, the body is limited to 64 KB (413 body_too_large).
• Ordering a number requires the header (400 missing_parameter without it).

The SDKs send a key on every POST (yours, or a generated one reused across retries).

Rate limits

Requests are limited per project, 100 per second for API keys. Over the limit the API answers 429 rate_limit with Retry-After (seconds). Placing calls also has calls-per-second and simultaneous-call limits (429 rate_limit from POST /calls); see GET /limits.

Webhooks and events

Contactivity calls your URLs for CoXML documents, status callbacks and call-control events. Every request is signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature, Ed25519); the public key is at GET /webhook-public-key, and the SDKs verify it with verifyStandardWebhook / verify_standard_webhook. Voice apps with param_style: "contactivity" receive events in the native envelope {id, type, created_at, project_id, data}; see Events and webhooks.

Versioning

The version is in the URL (/v1). Additive changes (new endpoints, fields, event types, error codes) ship without notice, so ignore fields you do not know. Breaking changes come as a new major version with at least 12 months of overlap; deprecated endpoints send Deprecation and Sunset headers.