Skip to main content
PATCH
/
api
/
phone-numbers
/
{phone-number}
curl -X PATCH "https://api.zudu.ai/api/phone-numbers/+14155551234" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \
  -d '{
    "nickname": "Updated Office Line",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456",
    "inbound_webhook_url": "https://example.com/webhook"
  }'

{
  "message": "Phone number updated successfully",
  "status": "success",
  "error": null,
  "data": {
    "phone_number": "+14155551234",
    "nickname": "Updated Office Line",
    "organization_id": "org_1234567890",
    "area_code": 415,
    "phone_number_type": "ZUDU_TWILIO",
    "number_provider": "twilio",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456",
    "inbound_webhook_url": "https://example.com/webhook",
    "updated_at": "2024-01-15T11:00:00Z"
  }
Update a phone number’s configuration including nickname, agent assignments, webhook URLs, and other settings. Only provided fields will be updated. 
curl -X PATCH "https://api.zudu.ai/api/phone-numbers/+14155551234" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \
  -d '{
    "nickname": "Updated Office Line",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456",
    "inbound_webhook_url": "https://example.com/webhook"
  }'

{
  "message": "Phone number updated successfully",
  "status": "success",
  "error": null,
  "data": {
    "phone_number": "+14155551234",
    "nickname": "Updated Office Line",
    "organization_id": "org_1234567890",
    "area_code": 415,
    "phone_number_type": "ZUDU_TWILIO",
    "number_provider": "twilio",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456",
    "inbound_webhook_url": "https://example.com/webhook",
    "updated_at": "2024-01-15T11:00:00Z"
  }

​
Path Parameters

​
phone-number
string
required
The phone number to update in E.164 formatExample: +14155551234Note: The phone number should be URL-encoded if it contains special characters (e.g., %2B14155551234 for +14155551234)

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Request Body

All fields are optional. Only provided fields will be updated.
​
nickname
string
Update the nickname/label for the phone numberAlternative field name: label (both are accepted)Example: "Updated Office Line"
​
inbound_agent_id
string
Update the agent ID assigned for inbound callsSet to null to unassign the inbound agentExample: "agent_123"
​
outbound_agent_id
string
Update the agent ID assigned for outbound callsSet to null to unassign the outbound agentExample: "agent_456"
​
inbound_agent_version
integer
Update the inbound agent versionExample: 1
​
outbound_agent_version
integer
Update the outbound agent versionExample: 1
​
inbound_webhook_url
string
Update the webhook URL for inbound callsExample: "https://example.com/webhook"
​
outbound_trunk_id
string
Update the outbound trunk IDExample: "trunk_outbound_abc123"
​
number_provider
string
Update the number providerExample: "twilio"

​
Response Fields

​
phone_number
string
The phone number in E.164 format
​
nickname
string
Updated nickname/label
​
organization_id
string
The organization ID
​
area_code
integer
Area code (for US numbers)
​
phone_number_type
string
Type of phone number
​
number_provider
string
Provider name
​
inbound_agent_id
string
Assigned inbound agent ID (or null)
​
outbound_agent_id
string
Assigned outbound agent ID (or null)
​
inbound_webhook_url
string
Webhook URL for inbound calls (if set)
​
updated_at
string
ISO 8601 timestamp when the phone number was last updated

​
Error Responses

​
error
string
Bad Request - Validation error
{
  "message": "Validation error",
  "status": "error",
  "error": "Invalid webhook URL format"
}
​
error
string
Unauthorized - Missing or invalid API key/secret
​
error
string
Not Found - Phone number does not exist
{
  "message": "Phone number not found",
  "status": "error",
  "error": "Phone number '+14155551234' does not exist in organization 'org_1234567890'"
}
​
error
string
Internal Server Error - Failed to update phone number
{
  "message": "Failed to update phone number",
  "status": "error",
  "error": "Database connection failed"
}

​
Notes

  • Only provided fields in the request body will be updated
  • Fields not included in the request will remain unchanged
  • Phone number, organization ID, area code, and phone number type cannot be updated
  • Use null to unassign agents (e.g., "inbound_agent_id": null)
  • Both nickname and label field names are accepted for updating the nickname
  • Phone numbers should be URL-encoded in the path (e.g., %2B for +)
  • The updated_at timestamp is automatically updated when any field changes