Skip to content
DashboardGet API key

List phone numbers

View .md
GET

List all phone numbers owned by this project.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Query parameters

  • statusstring

    Filter by phone number status.

    One ofactivesuspendedpendingreleasingreleased
  • limitinteger
    Default50
    Limitsmax 100
  • cursorstring

    Pagination cursor.

Responses

200List of phone numbers.
  • itemsobject[]required
    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>
  • nextCursorstringnullable
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject