Phone Numbers

Search, purchase, manage, and port phone numbers attached to your account.

Search available numbers

GET /api/v1/phone-numbers/search?country=US&areaCode=415&type=local&capabilities=voice,sms

Returns up to 50 candidate numbers from the upstream carrier. Numbers returned are reservations valid for ~5 minutes — purchase quickly.

Purchase a number

POST /api/v1/phone-numbers/purchase
Idempotency-Key: <uuid>
Content-Type: application/json
 
{
  "phoneNumber": "+14155551234",
  "campaignId": "cmp_xxx"      // Optional — assign immediately on purchase
}

Billing happens server-side via Stripe. Returns 201 with the persisted phone number record once the carrier confirms.

409 Conflict if the number was bought by someone else between search and purchase. Re-search and try again.

List your numbers

GET /api/v1/phone-numbers?campaignId=cmp_xxx

Update routing

PATCH /api/v1/phone-numbers/:id
Content-Type: application/json
 
{
  "campaignId": "cmp_yyy",
  "isActive": true
}

Setting campaignId to null returns the number to the unassigned pool — inbound calls will fall through to the account’s default routing.

Release a number

DELETE /api/v1/phone-numbers/:id

Releases the number back to the carrier. Irreversible — once released, the number can be claimed by anyone. Active calls on the number complete normally before release.

Port-in

Porting an existing number into Akol is a multi-step async process. Initiate:

POST /api/v1/phone-numbers/port-in
Content-Type: application/json
 
{
  "phoneNumber": "+14155551234",
  "loaSignedAt": "2026-04-18",
  "accountHolder": "Acme Inc."
}

You’ll be guided through uploading the LOA (Letter of Authorization) and recent bill. Port-in typically takes 5–10 business days. Subscribe to the port-order.status_changed webhook for updates.