Buy a phone number

Your organization can own US local numbers. A Resia number can be the caller number on outbound calls, answer inbound calls and texts, and send texts once it is on a 10DLC campaign. In this guide, you will search for a number, order it, and confirm the order.

Before you start

• Complete Get access. Keep that terminal open, with RESIA_API_BASE and RESIA_API_KEY set.
• A prepaid balance for the monthly rent. See Billing.

Search for a number

Narrow the search by area code, city, or state. A search reserves and charges nothing.

curl --fail-with-body --silent --show-error --get \
  "$RESIA_API_BASE/v1/available-phone-numbers" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --data-urlencode 'area_code=212' \
  --data-urlencode 'limit=5' \
  --output available-numbers.json

jq '.phone_numbers[] | {phone_number, cost_information}' available-numbers.json

Expected result: HTTP 200 with numbers and their cost_information. Resia charges no purchase fee; you pay the monthly rent.

In the portal: open Numbers and select Buy a number. Search by Area code, City, or State.

API reference: Search numbers you could buy.

Order the number

read -r -p 'The number to buy, including + and country code: ' NEW_PHONE_NUMBER

jq -n --arg number "$NEW_PHONE_NUMBER" '{phone_number: $number}' > number-order.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/phone-number-orders" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @number-order.json \
  --output number-order-response.json

jq '{phone_number_order_id, phone_number, status}' number-order-response.json

Expected result: HTTP 202 with the order in the pending state. The carrier completes the purchase in the background, usually within a minute.

In the portal: select Buy next to the number. The page waits for the carrier to confirm the order.

API reference: Buy a phone number.

Confirm the order

ORDER_ID=$(jq -er '.phone_number_order_id' number-order-response.json)

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/phone-number-orders/$ORDER_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  | jq '{status, phone_number}'

Expected result: status is ready. Read again while it is pending. The number then appears in your number list. You can use it as the caller number once Resia has confirmed with the carrier that it is live.

A purchase has no charge. Rent applies for each full calendar month that you own the number, starting with the first full month after the purchase.

In the portal: the dialog shows Waiting for the carrier to confirm the order… until the carrier answers. The number then appears on Numbers.

API reference: Check a number purchase and List your phone numbers.

If something fails

• No numbers match the search: try another area code, city, or state.
• The order is failed: the carrier could not complete the purchase, and nothing was added. Search again and order another number.
• 422 when you order: the number is not in E.164 form, such as +12125550199, or it is not one of the search results.

Next steps

• Receive an inbound call: let a Call Agent answer the number.
• Register for 10DLC texting: required before the number sends texts.
• Phone numbers: callbacks, costs, and how to release a number.