Phone numbers

Search available numbers

curl "https://api.anthonyoliva.com/v1/numbers/available?area_code=315&capabilities=sms,mms&limit=10" \
  -u "$AO_KEY_ID:$AO_KEY_SECRET"

Inventory is queried live against the upstream carrier, so a result that appears available generally is. It is still possible for another buyer to take it between search and purchase, which returns 409 number_unavailable.

Buy a number

curl https://api.anthonyoliva.com/v1/numbers \
  -u "$AO_KEY_ID:$AO_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2a1c5b90-73de-4f01-9c8a-6b2e5d1f7a44" \
  -d '{ "phone_number": "+13155550142", "campaign_id": "C7X4M2P" }'

Passing campaign_id at purchase attaches the number immediately. You can also attach later. A number cannot send A2P traffic until it is attached to an approved campaign.

Configure

curl -X PATCH https://api.anthonyoliva.com/v1/numbers/+13155550142 \
  -u "$AO_KEY_ID:$AO_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "Syracuse clinic reminders",
    "inbound_webhook_url": "https://example.com/hooks/inbound",
    "help_message": "Northgate Dental. For help call (315) 555-0133. Reply STOP to cancel."
  }'

If you override help_message, your text must still contain the program name and a way to reach a human. We validate this on write and reject a HELP response that does not, because an inadequate HELP reply is a carrier violation.

You cannot override the STOP behavior. Opt-out handling is enforced at the platform level.

Release

curl -X DELETE https://api.anthonyoliva.com/v1/numbers/+13155550142 \
  -u "$AO_KEY_ID:$AO_KEY_SECRET"

Billing stops at the end of the current cycle. Released numbers go back to the carrier pool and cannot be recovered. Any suppression list entries tied to the number are retained for audit purposes.

Porting

Bring numbers you already own.

curl https://api.anthonyoliva.com/v1/ports \
  -u "$AO_KEY_ID:$AO_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+13155550142", "+13155550143"],
    "current_carrier": "Example Telecom",
    "account_number": "884213",
    "authorized_signer": "Dana Whitfield",
    "service_address": {
      "street": "418 Erie Boulevard West",
      "city": "Syracuse",
      "state": "NY",
      "postal_code": "13202"
    }
  }'

The service address must match your losing carrier’s records exactly. A mismatched address is the usual cause of a port rejection. Typical elapsed time is 7 to 14 business days.

Numbers are attached to your campaign at cutover, so there is no window where traffic is unregistered.

Pricing

Numbers are billed from the day of purchase, prorated for the first month.