Phone Number Management API: List, Get, Update, Delete

Overview

Beyond creating a phone number, the API provides four lifecycle endpoints for working with numbers you've already provisioned. See Phone Provisioning for the Create endpoint, and Phone Number Fallback Destination & Inbound Settings for the fields you'd typically send in an Update request. This page is specifically the CRUD/lifecycle endpoint reference.

All four endpoints require a private API key sent as a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

List Phone Numbers

GET https://api.sulus.ai/phone-number

Returns the phone numbers belonging to your account. Supports the same pagination query parameters used elsewhere in the API, plus a pair for filtering by last-updated time:

Parameter	Type	Description
`limit`	number	Maximum number of items to return.
`createdAtGt` / `createdAtLt` / `createdAtGe` / `createdAtLe`	date-time	Filter by `createdAt` being greater than, less than, greater-or-equal, or less-or-equal the given value.
`updatedAtGt` / `updatedAtLt` / `updatedAtGe` / `updatedAtLe`	date-time	Same comparisons, filtered on `updatedAt` instead — useful for finding numbers changed since a given point in time.

Get Phone Number

GET https://api.sulus.ai/phone-number/{id}

Returns the full phone number resource for the given ID, including its current status. This works the same way regardless of whether the number is a free platform-provided number, a bring-your-own number, or one imported from an external carrier — you can check status on any of them through this single endpoint.

Parameter	Location	Required	Description
`id`	path	Yes	The unique identifier of the phone number.

Update Phone Number

PATCH https://api.sulus.ai/phone-number/{id}

Updates the specified fields on the phone number resource, leaving the rest untouched. A simple rename example:

curl -X PATCH https://api.sulus.ai/phone-number/{id} \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support Line" }'

Delete Phone Number

DELETE https://api.sulus.ai/phone-number/{id}

Permanently removes the phone number resource from your account.

curl -X DELETE https://api.sulus.ai/phone-number/{id} \
  -H "Authorization: Bearer <your-api-key>"

Deleting a number does not release it back to a carrier automatically for bring-your-own or imported numbers — check your provider's own console if you also need to release or cancel the number there.

On this page

Phone Number Management API: List, Get, Update, Delete