DELETEhttps://core-api.heysadie.ai/phone-numbers/{id}
id success data status phoneNumberId phoneNumber metadata timestamp version path error code message details fieldDelete phone number
Releases a phone number from your tenant account and stops all associated billing. **Process:** 1. Validates ownership - ensures the phone number belongs to your tenant 2. Unlinks assistant - removes the phone number from any associated assistant 3. Releases from Twilio - stops billing and returns the number to inventory 4. Cleans database - marks the number as deleted in your account **Important:** - Once released, the phone number becomes available for other customers to purchase - Billing stops immediately upon successful Twilio release - If Twilio release fails, the database record is still marked deleted; manual cleanup on the provider side may be required **Response:** The response includes status information confirming the release.
Try it in the API ExplorerExample request
curl -X DELETE "https://core-api.heysadie.ai/phone-numbers/PHONE_NUMBER_ID" \
-H "Authorization: ApiKey YOUR_API_KEY"Authentication
Authenticate with an API key in the Authorization header using the ApiKey scheme — see Authentication for how keys work and where to get them.
AuthorizationstringrequiredAPI key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.
X-Tenant-Idstring (uuid)optionalRequired when authenticating with an organization key — selects the tenant the request acts on. Omit with tenant keys.
Request
Path parameters
idstringrequiredThe resource's UUID.
Responses
successbooleanrequireddataobjectoptionalShow 3 child properties
statusstringrequiredRelease status
phoneNumberIdstringrequiredID of the released phone number
phoneNumberstringrequiredThe phone number that was released
metadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional400
successbooleanrequirederrorobjectoptionalShow 3 child properties
codeenumrequired"VALIDATION_ERROR"messagestringrequireddetailsobject[]optionalShow 2 item properties
fieldstringrequiredmessagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional401
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"UNAUTHORIZED"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional403
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"FORBIDDEN"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional404
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"RESOURCE_NOT_FOUND"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional500
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"INTERNAL_SERVER_ERROR"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional