Delete Phone Number

Delete a phone number and clean up external resources (Twilio trunk configuration).

HTTP Request

$
DELETE https://app.resemble.ai/api/v2/phone_numbers/{id}

URL Parameters

Example Request

$
curl --request DELETE "https://app.resemble.ai/api/v2/phone_numbers/1" \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json"

Response (Success)

1
{
2
  "success": true,
3
  "message": "Phone number deleted successfully"
4
}

Response (Corrupted - Cleanup Failed)

1
{
2
  "success": false,
3
  "errors": {
4
    "base": ["Failed to cleanup external resources. Phone number marked as corrupted. Please see documentation for manual cleanup: https://docs.resemble.ai/phone-numbers/cleanup"]
5
  },
6
  "message": "Failed to delete phone number"
7
}

Cleanup Process

When deleting a phone number:

1. Status Update: Phone number is marked as “deleting”
2. Twilio Cleanup (if configured):
   • Deletes SIP trunk
   • Removes credential lists
   • Removes connection policies
3. Database Deletion: Phone number record is deleted

Failure Handling

If Twilio cleanup fails:

• Phone number is marked as “corrupted”
• Phone number record is kept in database
• Error message includes cleanup instructions
• Use Force Delete to remove corrupted phone numbers

Common Error Scenarios

Invalid Twilio Credentials

If Twilio credentials are invalid or expired during deletion:

1
{
2
  "success": false,
3
  "errors": {
4
    "base": ["Failed to cleanup external resources. Phone number marked as corrupted."]
5
  },
6
  "message": "Failed to delete phone number"
7
}

Resolution:

1. Manually clean up Twilio trunk in Twilio console
2. Use Force Delete to remove the phone number record

Network Errors

If network issues prevent communication with Twilio:

1
{
2
  "success": false,
3
  "errors": {
4
    "base": ["Failed to cleanup external resources. Phone number marked as corrupted."]
5
  },
6
  "message": "Failed to delete phone number"
7
}

Resolution:

1. Wait for network connectivity to restore
2. Retry deletion (system will attempt cleanup again)
3. If issues persist, manually clean up and use Force Delete

Important Notes

• Agent unlinking: Phone numbers are automatically unlinked from agents before deletion
• Permanent action: Deletion cannot be undone
• External cleanup: Twilio resources are removed to prevent orphaned configurations
• Corrupted state: Failed cleanup results in corrupted state requiring manual intervention

See Also

• Force Delete Phone Number - Force delete corrupted phone numbers
• Phone Numbers Overview - Learn about phone number management