Skip to content
DashboardGet API key

Update phone number

View .md
PATCH

Update a phone number's name or sender assignment.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • phoneNumberIdstringrequired

Body

application/json

  • namestringnullable

    Custom name for the phone number. Set to null to clear.

    Limitsmax length 100
  • senderIdstringnullable

    Sender ID to assign the phone number to. Set to null to unassign. A number under regulatory review is recorded now and connected to the sender when approved; a rejected number is refused.

Responses

200Phone number updated.
  • phoneNumberobjectrequired
    12 properties
    • idstringrequired
    • phoneNumberstringrequired
    • namestring

      Optional custom name for the phone number.

    • capabilitiesstring[]required
    • statusstringrequired

      Billing state of an owned number, separate from regulatoryStatus. pending is legacy and is not written to numbers today. The SDKs carry active, suspended and pending only; releasing and released are returned by the REST API until their next release.

      One ofactivesuspendedpendingreleasingreleased
    • senderIdstring

      Sender ID if the phone number is assigned to a sender.

    • pricingobjectrequired
      4 properties
      • monthlyPricenumber

        Monthly price in USD.

      • upfrontCostnumber

        One-time purchase cost in cents.

      • monthlyCostnumber

        Monthly cost in cents.

      • isFreeNumberboolean

        Whether this is a free number.

    • regulatoryStatusstringrequired

      Regulatory review state. Numbers that need no review are approved immediately. A number bought with regulatory information is owned and billed from purchase and starts pending_review; it cannot send messages or place calls until this is approved. The state is re-checked every 6 hours: poll GET /v1/phone-numbers/{phoneNumberId} to follow it.

      Assign it to a sender with PATCH /v1/phone-numbers/{phoneNumberId} (senderId) before or after approval. A number assigned while under review is recorded and connected to that sender when it is approved; the connection is retried until it succeeds. A sender created over the API is set up for SMS as part of the assignment. rejected means review refused the information: the number cannot be assigned to a sender. A number that stays pending_review may be waiting on information the API cannot supply; contact support.

      One ofapprovedpending_reviewrejected
    • nextRenewalDatestring<date-time>
    • releaseAtstring<date-time>

      When the number goes back to the carrier, if it is on its way out. Absent otherwise.

      • A paid plan ended. Without a paid plan a team keeps one number: the one chosen in the dashboard when cancelling, else the one the plan included, else the oldest it bought. That number is billed monthly from the balance and has no releaseAt unless a renewal fails. Every other number keeps working, unbilled, until this date, 7 days after the plan ended. Numbers you brought yourself are never released.
      • A renewal could not be paid. The number is suspended and released at the end of a 7-day grace.

      Paying, or returning to a paid plan, before this date keeps the number. A released number cannot be recovered.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>
400Invalid request, or the number was rejected in regulatory review and cannot be assigned to a sender.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Phone number or sender not found.
  • codestringrequired
  • messagestringrequired
  • detailsobject
503The sender could not be set up for SMS right now. Nothing was assigned; retry.
  • codestringrequired
  • messagestringrequired
  • detailsobject