Skip to main content
Carrier credentials and phone-number management. Wrapped by the Python SDK and Node SDK.

​
Endpoints at a glance

MethodPathSummary
GET/api/v1/telephony/numbersList phone numbers
POST/api/v1/telephony/numbersRegister a phone number
PATCH/api/v1/telephony/numbers/{id}Pin or unpin a phone number to an agent
DELETE/api/v1/telephony/numbers/{id}Delete a phone number
GET/api/v1/telephony/providersList telephony provider credentials
POST/api/v1/telephony/providersAdd a telephony provider credential
DELETE/api/v1/telephony/providers/{id}Delete a telephony provider credential

​
Reference

​
GET /api/v1/telephony/numbers

List phone numbers Parameters
NameInTypeRequiredDescription
agent_idquerystringNoFilter by agent id
Responses
CodeDescriptionBody
200OKobject
500Database errorstring
Example 
curl https://api.kataven.ai/v1/telephony/numbers \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/telephony/numbers

Register a phone number Binds an E.164 number to a carrier credential row and (optionally) pins it to one agent. Inbound + outbound default to enabled. Request body (application/json) Schema: handlers.CreateNumberRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
agent_idstringe.g. agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
credentials_idstringe.g. prov_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
e164stringe.g. +12025550123
inbound_enabledbooleane.g. True
outbound_enabledbooleane.g. True
providerstringe.g. twilio
Responses
CodeDescriptionBody
201Createdobject
400Invalid body or duplicate numberstring
Example 
curl https://api.kataven.ai/v1/telephony/numbers \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
  "credentials_id": "prov_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
  "e164": "+12025550123",
  "inbound_enabled": true,
  "outbound_enabled": true,
  "provider": "twilio"
}'

​
PATCH /api/v1/telephony/numbers/{id}

Pin or unpin a phone number to an agent Parameters
NameInTypeRequiredDescription
idpathstringYesPhone number id (uuid)
Request body (application/json) Schema: handlers.UpdateNumberRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
agent_idstringe.g. agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
Responses
CodeDescriptionBody
204Updated—
404Phone number not foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/telephony/numbers/agent_01HZ2N... \
  -X PATCH \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z"
}'

​
DELETE /api/v1/telephony/numbers/{id}

Delete a phone number Parameters
NameInTypeRequiredDescription
idpathstringYesPhone number id (uuid)
Responses
CodeDescriptionBody
204Deleted—
404Phone number not foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/telephony/numbers/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
GET /api/v1/telephony/providers

List telephony provider credentials Returns metadata about every carrier credential configured for this account. Plaintext credentials are not returned. Responses
CodeDescriptionBody
200OKobject
400Missing X-Account-ID headerstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/telephony/providers \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/telephony/providers

Add a telephony provider credential Encrypts the credentials JSON via the Secret Encryptor service, then inserts the row. Plaintext is never persisted. Request body (application/json) Schema: handlers.CreateProviderRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
credentialsobject
labelstringe.g. Production Twilio
providerstringe.g. twilio
Responses
CodeDescriptionBody
201Createdobject
400Invalid body or missing fieldstring
500Database errorstring
503Encryption service unavailablestring
Example 
curl https://api.kataven.ai/v1/telephony/providers \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Production Twilio",
  "provider": "twilio"
}'

​
DELETE /api/v1/telephony/providers/{id}

Delete a telephony provider credential Refuses if any phone-number row still references this credential — detach numbers first. Parameters
NameInTypeRequiredDescription
idpathstringYesCredential id (uuid)
Responses
CodeDescriptionBody
204Deleted—
404Credential not foundstring
409Credential in use by phone numbersstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/telephony/providers/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"