Skip to main content
DELETE
Delete Phone Number
Destructive
Recommended. This endpoint is part of the public /v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.
Deletes a phone number from your DialNexa workspace. The delete operation soft-deletes the workspace record and stops future use of that number in DialNexa. If the number is connected through a SIP trunk, DialNexa also removes the media-server trunk and SIP credentials. If the number was rented through a provider, DialNexa releases the rental and deactivates the active rental subscription.

When to use this

  • Workspace cleanup: remove numbers you no longer use for inbound or outbound calls.
  • SIP trunk teardown: remove a bring-your-own number and its SIP routing credentials from DialNexa.
  • Cost control: stop future rental activity for numbers that should no longer be billed through the workspace.
Do not call this endpoint for numbers that are still part of an active production flow. If you only need to inspect the number first, use Get Phone Number Details.

Before you delete

Confirm these conditions before sending the request:
  • The number is not your organization’s default phone number.
  • No active workflows are using the number.
  • Any inbound routing that depends on this number has been moved to another number.
  • You are comfortable losing the current provider rental or SIP trunk connection.

Example request

Result

A successful request returns 200 OK. After deletion, the number no longer appears in List Phone Numbers.

Errors

  • 400 Bad Request is returned when the phone number ID format is invalid.
  • 403 Forbidden is returned when the phone number does not belong to your organization.
  • 404 Not Found is returned when the phone number does not exist or has already been deleted.
  • 409 Conflict is returned when the number is the organization default or is used by active workflows. Move the default number or deactivate the workflows, then retry.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

Phone number ID

Example:

"phn_abc123"

Response

Phone number deleted successfully.