Contactivity API reference

The Contactivity API places and controls calls, manages numbers, trunks and voice apps, runs AI agents 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 https://api.contactivity.io/docs/openapi.yaml (OpenAPI 3.1). The SDKs are @contactivity/sdk (Node) and contactivity_sdk (Python). Moving from Twilio or Telnyx? See compatibility.md.

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. 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, flow or AI agent is handled like a missing one, an alert rule stops firing, a caller ID cannot be used, a queue refuses new callers, a knowledge base or document leaves search.
• 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, AI agent transcripts, summaries and data, 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), except knowledge-base documents and voice-clone uploads, which keep their own limits.
• 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, call-control events and AI agent tools. 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.md.

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.