Trillet AI logo

Release Phone Number

Release a phone number from your workspace, or cancel its renewal if it's a paid number.

POSThttps://api.trillet.ai/v1/api/twilio/release-number

What happens depends on the number:

  • Paid number with a subscription. The number is not removed now. Its monthly renewal is cancelled, and the number keeps working until the end of the period you've already paid for. The response includes scheduledReleaseAt, the date it will be removed. To keep the number after all, call POST /v1/api/twilio/phone-numbers/{phoneNumberSid}/cancel-release before that date.
  • Every other number (numbers from your plan's free allowance, numbers you brought yourself, numbers with nothing left to bill) is released immediately.

Your role needs the phone_number:delete permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

phoneNumberSidstringrequired

The number's sid from List Phone Numbers. This is the provider's ID for the number (for a SIP number you brought yourself, it's the number in E.164 format). It is not the record _id: sending the _id returns 404.

Response

Released immediately

successboolean

true.

phoneNumberSidstring

The sid you sent. Depending on the kind of number, the response can carry phoneNumber and message instead. Rely only on success.

Renewal cancelled (paid number)

The response is the Stripe subscription after the change (for example id, status and cancel_at_period_end: true), plus:

scheduledReleaseAtstring

When the number will be removed, as an ISO 8601 time. null if Stripe returned no period end.

Errors

StatusBodyWhen
400{"error": "Workspace ID is required."}No x-workspace-id
403{"error": "Phone number release is not allowed for SMB accounts. ..."}SMB accounts can't release numbers. Contact support
404{"error": "Phone number not found"}No number with that sid in this workspace
500{"error": "..."}The release failed at the provider or in Stripe

Cancel a scheduled release

POST /v1/api/twilio/phone-numbers/{phoneNumberSid}/cancel-release (no body) turns the renewal back on and returns the number with scheduledReleaseAt: null. It returns 400 with code NO_SCHEDULED_RELEASE when the number isn't scheduled for release, 400 with RELEASE_DATE_PASSED once the date has passed, and 404 with NOT_FOUND for an unknown number.

{
  "phoneNumberSid": "1293384261075731499"
}
Released immediately
{
  "success": true,
  "phoneNumberSid": "1293384261075731499"
}
Renewal cancelled (trimmed)
{
  "id": "sub_1QabcDEFghIJklMN",
  "object": "subscription",
  "status": "active",
  "cancel_at_period_end": true,
  "scheduledReleaseAt": "2026-11-28T09:14:02.000Z"
}

Last updated on