SIP trunks, routes and project settings

SIP trunks connect your phones, PBX or SIP provider to Contactivity. Routes decide where a number's inbound calls go. This page also covers the project's limits and the webhook public key.

All paths are relative to https://api.contactivity.io/v1/projects/{project_id}. Authentication, errors, paging and idempotency work as described in the overview.

PATCH requests change only the fields you send; the result is checked like a create. Every write is recorded in the project's audit log with the API key's id.

Trunks

The trunk object

Create or update a trunk

Errors: 400 invalid_parameter (param name, auth_type, hosts, default_caller_id, ring_strategy, ring_secs or cps_limit), 400 invalid_request (a host that is invalid, not public or already in use), 400 unknown_parameter, 400 invalid_json, 404 not_found (PATCH), 409 already_exists.

Archiving a trunk (DELETE) also archives its SIP credentials and IPs: they stop authenticating and routing at once. A trunk that an active route or PBX app uses is refused with 409 in_use. An archived SIP credential's username and an archived IP can be used again; ?archived=true on the credentials and IPs lists shows archived ones. An archived route stops routing: numbers pointing at it are unrouted in effect.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/trunks \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Office PBX", "auth_type": "host", "hosts": ["203.0.113.10:5060"], "recording": true}'

SIP credentials (register trunks)

Phones and PBXs register with a username and password. Only a digest hash of the password is stored.

The response is {"username", "domain", "trunk_id", "position"}; domain is where the phone registers (your organization's SIP domain). The list returns {"username", "domain", "position"} items in ring order, in one page (has_more is always false).

Errors: 400 invalid_parameter (param username, password, position), 400 invalid_request (the trunk is not a register trunk), 404 not_found, 409 already_exists (username taken). Deleting a phone that a PBX app rings returns 409 in_use.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/trunks/$TRUNK_ID/credentials \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"username": "frontdesk-101", "password": "correct-horse-battery"}'

Ring strategy

Each SIP credential of a register trunk is one device (all phones registered under it ring together). An inbound call, or a PBX app dialing the trunk, rings them by the trunk's ring_strategy:

Devices with no registration are skipped. The route's ring timeout still ends the call. A device that is busy or does not answer passes the call to the next one; a decline (603) ends it. When none is left the caller gets 486 (last one busy) or 480.

PUT /trunks/{trunk_id}/credentials/order with {"usernames": [...]} sets the order: every active credential of the trunk once, first to ring first. It returns the credentials in their new order. Errors: 400 invalid_parameter (param usernames), 400 invalid_request (not a register trunk), 404 not_found.

curl -X PUT https://api.contactivity.io/v1/projects/$PROJECT_ID/trunks/$TRUNK_ID/credentials/order \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"usernames": ["frontdesk-101", "frontdesk-102"]}'

Allowed IPs (ip trunks)

POST {"cidr": "203.0.113.0/29"} allows a public IP (203.0.113.7) or a network of at most /29 (IPv4) or /125 (IPv6); host bits are masked. A range that overlaps any trunk or carrier range is refused with 409 already_exists. Items are {"id", "ip_addr", "mask"} (id is a numeric string); the list is one page and also shows the IP hosts of a host trunk.

Errors: 400 invalid_parameter (param cidr), 400 invalid_request (the trunk is not an ip trunk), 404 not_found, 409 already_exists.

Routes

A route sends inbound calls somewhere. Point a number at it with PATCH /numbers/{e164} (route_id).

The route object

Create or update a route

Errors: 400 invalid_parameter (param type, target, mode, failover_codes, ring_timeout, fallback_route_id), 400 invalid_request (percentage mode on a non-forward route, scope given, blocked destination), 400 unknown_parameter, 404 not_found (PATCH).

Deleting a route unroutes the numbers that pointed at it and clears other routes' fallback to it.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/routes \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type": "trunk", "target": "'$TRUNK_ID'", "ring_timeout": 25}'

curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/routes?type=trunk&limit=20" \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY"

Limits

GET /limits (any key of the project) returns:

Limits are set by Contactivity; contact support to change them.

Webhook public key

GET /webhook-public-key (any key of the project) returns:

{"algorithm": "ed25519", "public_key": "<base64>", "previous_public_key": "<base64>" | null,
 "previous_expires_at": "2026-10-23T09:00:00.000Z" | null, "rotated_at": "2026-10-22T09:00:00.000Z" | null}

public_key verifies the webhook-signature header on every webhook, CoXML fetch and AI tool call. Until the project rotates its key this is the platform key and rotated_at is null. The SDKs' verifyStandardWebhook / verify_standard_webhook take this key.

POST /webhook-public-key/rotate (scope events:write; in the portal, an organization owner/admin or project admin) makes a new key and returns the same body. The replaced key keeps signing for 24 h (previous_public_key until previous_expires_at): during that time webhook-signature carries two space-separated v1a, entries, the new key's first, so a receiver that trusts either key keeps working. Other servers pick up a rotation within a minute; rotating again within 24 h drops the oldest key at once.

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