Release a Number

Release a purchased phone number from your account and stop billing for it at the end of the current cycle.

DELETE /organization-phone-numbers/{id}

Release a phone number

cURL

curl --request DELETE \
  --url https://api.dialnexa.com/v1/organization-phone-numbers/{id} \
  --header 'Authorization: Bearer <token>'

200

{
  "message": "Phone number released successfully."
}

Releases a phone number back to the upstream telephony provider’s pool. The number is removed from your account immediately, any active inbound routing on the number is detached, and billing for the number stops at the end of the current billing cycle. This action is irreversible, once a number is released, DialNexa cannot guarantee it can be re-purchased, and most provider pools recycle numbers to new customers.

When to use this

Release a number when you no longer need it on this workspace. Common cases:

• Retiring a campaign number that is no longer in active use.
• Decommissioning a region where you no longer run outbound or inbound calls.
• Consolidating numbers after a workspace cleanup.

If you only want to stop using the number with a specific agent, for example because you are moving the agent to a different number, call Update Phone Number and clear the agent_id field instead. The number stays on your account and can be reassigned later.

Behavior

• Inbound calls arriving on the number after release fail at the carrier layer.
• Outbound calls already in progress on the number are not interrupted.
• Provider-side number reservation may not be reclaimable, releasing a number you might want to keep is a one-way action.
• Billing stops at the end of the current billing cycle, not at the moment of release.

Path parameters

Parameter	Description
id	The phone number ID, for example phn_f7w2kx5mb9qz.

Errors

• 404 Not Found is returned when the phone number does not exist on this workspace.
• 409 Conflict is returned when the number is part of an active campaign that must be reconfigured before release.

Request

curl -X DELETE "https://api.dialnexa.com/v1/organization-phone-numbers/phn_f7w2kx5mb9qz" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{ "message": "success" }

Related endpoints

• Update Phone Number: reassign or detach the number without releasing it.
• Buy a Phone Number: purchase a replacement number.
• List Phone Numbers: confirm the release and review remaining numbers.

Authorizations

Authorization · string · header · required

Pass your API key as a Bearer token in the Authorization header.

Path Parameters

id · string · required

Response

200

application/json

Success.

message · string

Example:

"Phone number released successfully."