Skip to content
DashboardGet API key

Purchase a phone number

View .md
POST

Purchase an available phone number. Requires a paid plan: the Free plan cannot purchase phone numbers and receives 402 with code paid_plan_required.

The included number. A paid plan includes one number at no charge, once per account: it must be a US or Canadian number (a +1 number) costing $20 a month or less. isFreeEligible in GET /v1/phone-numbers/available marks the numbers that qualify. Claiming it spends the benefit for good, across every team the account owner owns, so releasing that number does not make another one free.

Numbers with regulatory requirements. Which numbers need regulatory information is decided per number, not by a fixed country list. The purchase looks the requirements up for the exact number before charging anything:

  1. GET /v1/phone-numbers/requirements?phoneNumber=.... If items is empty, buy normally.
  2. Create what it asks for: addresses with POST /v1/addresses, documents with POST /v1/documents.
  3. Purchase with type and regulatoryRequirements. The number is bought and billed at once with regulatoryStatus: pending_review.
  4. Poll GET /v1/phone-numbers/{phoneNumberId} until regulatoryStatus is approved. Assign it to a sender before or after approval; it starts carrying messages once approved.

Reuse. Information you submitted is kept for your project, per country and type, and a later purchase there may omit regulatoryRequirements. Reuse only happens when what is kept still covers every requirement of the new number and every address and document in it belongs to the project. Otherwise, or when nothing is kept, the purchase returns 400 regulatory_compliance_required with the missing requirements in details.

Invalid values (a missing, unknown or repeated requirement id, an address or document from another project, or one rejected in review) return 400 invalid_request. If an address or document cannot be registered for review, the purchase returns 400 invalid_request naming the requirement. If the requirements cannot be looked up, the purchase returns 502 requirements_unavailable, except for US and Canadian numbers, which are sold as numbers without requirements. None of these errors charge anything.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • phoneNumberstringrequired

    Phone number in E.164 format.

  • namestring

    Optional custom name for the phone number.

    Limitsmax length 100
  • typestring

    Type the number was found under in GET /v1/phone-numbers/available. Used to look the number up and to keep regulatory information for reuse. Required when regulatoryRequirements is sent. toll_free is accepted as an alias of tollFree. A number not listed under this type is refused with 400 number_unavailable saying so.

    One oflocalnationaltollFreemobile
  • regulatoryRequirementsobject[]

    Regulatory information, for numbers whose requirements list is not empty. Get the list with GET /v1/phone-numbers/requirements?phoneNumber=... and send one entry per requirement id, except action requirements, which take no value. Every required id must be present, once, and no unknown id may be sent; otherwise the purchase is refused with 400 invalid_request before anything is charged.

    The information is kept for your project under the number's country and type. A later purchase there may omit this field if what is kept still covers that number's requirements. Omit it for numbers without requirements.

    Limitsmax items 50
    2 properties
    • requirementTypestringrequired

      A requirementTypes[].id from GET /v1/phone-numbers/requirements. Each id may appear only once.

      Limitsmin length 1 · max length 200
    • fieldValuestringrequired

      Depends on the requirement's type: the text itself for textual; for address, the id of an address created in this project with POST /v1/addresses; for document, the id of a document created with POST /v1/documents. An address or document from another project, or one rejected in review, is refused.

      Limitsmin length 1 · max length 1000

Responses

201Phone number purchased successfully.
  • 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, the number is no longer available or not listed under the `type` sent (`number_unavailable`), the country is restricted, regulatory information is missing (`regulatory_compliance_required`), or the regulatory information sent is invalid (`invalid_request`).
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
402Payment required. Either the balance cannot cover the purchase (code `insufficient_balance`) or the team is on the Free plan (code `paid_plan_required`): buying phone numbers requires a paid plan, which includes one US number.
  • codestringrequired
  • messagestringrequired
  • detailsobject
502The number's regulatory requirements could not be looked up, so nothing was charged. Retry. Not returned for US and Canadian numbers.
  • codestringrequired
  • messagestringrequired
  • detailsobject