Skip to main content

Piopiy Numbers

Overview​

Use Piopiy Numbers REST API to search, buy, list, and release phone numbers.

You can manage numbers in two ways:

  • Dashboard UI for manual setup
  • REST API for backend automation

Prerequisites​

  • Piopiy account with API access enabled
  • API authentication credentials from portal
  • Region/country and number type defined in your product logic

Option 1. Buy from Piopiy Dashboard (UI)​

Use this when your team wants a fast manual setup.

  1. Open the Piopiy Dashboard.
  2. Go to Numbers.
  3. Click Buy a Number.
  4. Select country and number type.
  5. Purchase the number.
  6. Manage purchased numbers from your dashboard list.

For full dashboard flow, see Dashboard Setup.

Option 2. Buy and Manage with REST API​

Use this when you need automated provisioning and backend control.

Set these variables before running requests:

export PIOPIY_API_KEY="your_api_key"
export PIOPIY_API_BASE="https://api.piopiy.com/v1"

1. Search Available Phone Numbers​

Find available inventory using filters such as region/country.

curl --request GET \
  --url "$PIOPIY_API_BASE/list-available-numbers?region=US" \
  --header "Authorization: Bearer $PIOPIY_API_KEY"

Use the returned number you want to purchase.

Example response:

{
  "data": [
    {
      "id": "num_8h3k1",
      "number": "+19499800001",
      "region": "US",
      "capabilities": ["voice"]
    }
  ],
  "next_cursor": null
}

2. Buy Phone Number (REST API)​

Purchase the chosen number programmatically.

curl --request POST \
  --url "$PIOPIY_API_BASE/buy-phone-number" \
  --header "Authorization: Bearer $PIOPIY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "number": "+19499800001"
  }'

Store the returned number id in your backend for operational workflows.

Example response:

{
  "id": "num_8h3k1",
  "number": "+19499800001",
  "status": "active"
}

3. List Purchased Phone Numbers​

Get all numbers currently purchased by your account.

curl --request GET \
  --url "$PIOPIY_API_BASE/purchased-phone-numbers" \
  --header "Authorization: Bearer $PIOPIY_API_KEY"

Example response:

{
  "data": [
    {
      "id": "num_8h3k1",
      "number": "+19499800001",
      "status": "active"
    }
  ]
}

4. Release Phone Number​

Release a number that is no longer needed.

curl --request DELETE \
  --url "$PIOPIY_API_BASE/release-phone-number/NUMBER_ID" \
  --header "Authorization: Bearer $PIOPIY_API_KEY"

Example response:

{
  "id": "num_8h3k1",
  "status": "released"
}

Production Checklist​

  • Keep one number pool per environment (staging/production).
  • Keep provisioning changes in backend automation.
  • Add idempotency + retries for buy/release flows.
  • Log request IDs and number status changes for auditability.
  • Verify purchased/released status after each operation.

Reference​