Delete a registered SIP phone number

Stop SpaceXAI from answering a Direct SIP or Twilio-imported line when you decommission a trunk, rotate webhook destinations by re-registering, or remove a test number from the team inventory. Official Voice REST documents DELETE https://api.x.ai/v2/phone-numbers/{phone_number_id} with Bearer API-key auth. A successful delete returns HTTP 204 with an empty body. The SIP Phone Calls guide states that delete tears down that number’s inbound SIP trunk and dispatch rule on the SpaceXAI side, that the webhook record can remain, and that the E.164 stays in your carrier account. SpaceXAI-provisioned numbers are not deleted this way — the API returns 403.

What you need

An inference API key on the team that owns the registration, and the phone_number_id from create or from List registered SIP phone numbers. Neighboring jobs include Handle SIP phone calls with Speech to Speech for the register and answer path, Transfer a SIP call with refer for mid-call handoff while a line is still live, and Resume a SIP conversation across calls when history should continue on a later dial-in. More voice jobs live on the Voice hub.

Delete by phone_number_id

Export the key, then DELETE the path id. Prefer listing first when you only remember the E.164 string.

export XAI_API_KEY="your_api_key"
PHONE_NUMBER_ID="phone_abc123"

curl -i -X DELETE "https://api.x.ai/v2/phone-numbers/${PHONE_NUMBER_ID}" \
  -H "Authorization: Bearer ${XAI_API_KEY}"

import os

import requests

phone_number_id = "phone_abc123"
response = requests.delete(
    f"https://api.x.ai/v2/phone-numbers/{phone_number_id}",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
)
if response.status_code == 204:
    print("deleted")
else:
    print(response.status_code, response.text)
    response.raise_for_status()

Expect 204 with no body on success. After delete, new INVITEs for that registration stop landing in your webhook. Update the carrier trunk if you still own the PSTN number and no longer want traffic pointed at sip:{number}@sip.voice.x.ai.

What delete does not remove

Docs are explicit: your carrier-side number and account stay put; SpaceXAI removes its inbound trunk binding and dispatch rule for that registration. Webhook configuration may still exist as a leftover record — do not assume delete wipes every Console object. Re-registering the same E.164 requires a fresh POST /v2/phone-numbers with webhook details again, and the signing secret is returned only once on create.

Pitfalls

Calling delete with the E.164 digits in the path instead of phone_number_id fails — resolve the id via list. Expecting an xAI-provisioned number to disappear returns 403; the guide says provisioning those numbers via API is unsupported for delete the same way. Deleting mid-campaign without updating the PBX leaves carriers sending INVITEs into a gone trunk. Confusing delete with hangup ends inventory instead of a single live call_id — hangup is POST /v1/realtime/calls/{call_id}/hangup while the caller is still connected.