Phone numbers

Beta. Every endpoint on this page is live and documented as shipped. Shapes can still change before general availability.

Overview

The Phone Numbers API lists the numbers your organization owns, searches carrier inventory, rents new numbers and releases numbers you no longer need.

Base URL: https://api.hirefinn.ai/api/v1. Auth: Authorization: Bearer finn_live_.... See authentication.

Assigning a number to a Finn is done by deploying. There is no assign or unassign endpoint. To answer calls on a number, create an inbound deployment for the Finn and the number; to dial from a number, use it in an outbound deployment. The number is freed when you stop the deployment or when it ends as completed or error, and can then be deployed again. See api-deployments.

Renting and releasing have real effects:

• Renting debits your wallet when the request is accepted, then provisions the number asynchronously.
• Releasing gives no refund. The number goes back to the carrier and is deleted from your organization.

Endpoints

The phone number object

{
  "id": "6b1f0c2e-3d4a-4f5b-9c8d-2e7a1b9f4c03",
  "phone_number": "+918035731234",
  "status": "Live",
  "provider": "plivo",
  "country": "IN",
  "capabilities": { "voice": true, "sms": false, "mms": false },
  "allocation": {
    "finn_id": "8f14e45f-ceea-467a-9f6a-1c0e5b2a77d1",
    "call_type": "inbound"
  },
  "created_at": "2026-09-02T11:20:41.000Z",
  "updated_at": "2026-09-02T11:21:05.000Z"
}

List numbers

GET /phone_numbers

Returns numbers owned by your organization, newest first.

curl "https://api.hirefinn.ai/api/v1/phone_numbers?limit=50" \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "6b1f0c2e-3d4a-4f5b-9c8d-2e7a1b9f4c03",
      "phone_number": "+918035731234",
      "status": "Live",
      "provider": "plivo",
      "country": "IN",
      "capabilities": { "voice": true, "sms": false, "mms": false },
      "allocation": null,
      "created_at": "2026-09-02T11:20:41.000Z",
      "updated_at": "2026-09-02T11:21:05.000Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

There is no total count. Page with offset until a page returns fewer than limit items.

Retrieve a number

GET /phone_numbers/{id}

curl https://api.hirefinn.ai/api/v1/phone_numbers/6b1f0c2e-3d4a-4f5b-9c8d-2e7a1b9f4c03 \
  -H "Authorization: Bearer $FINN_API_KEY"

Returns { "success": true, "data": { ... } } with one phone number object.

Search available numbers

GET /phone_numbers/available

curl "https://api.hirefinn.ai/api/v1/phone_numbers/available?country=US&search=415" \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": [
    {
      "phone_number": "+14155550123",
      "country": "US",
      "region": "CA",
      "locality": "San Francisco",
      "number_type": "local",
      "capabilities": { "voice": true, "sms": true, "mms": false },
      "price": null,
      "currency": null
    }
  ]
}

The list is not paginated. When the carrier has nothing matching, data is an empty array.

Some searches require your organization's compliance application to be approved, otherwise the search returns 409 compliance_required: searching India (IN) inventory, searching with provider=exotel, and searching without provider when your organization's default carrier is Exotel. Organizations with an approved application, or that already have a carrier subaccount, can search. Compliance is completed in the dashboard under Settings → Compliance, not through the API; the error's action_url (...settings?tab=telephony-account) opens that tab.

Rent a number

POST /phone_numbers

curl -X POST https://api.hirefinn.ai/api/v1/phone_numbers \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550123",
    "capabilities": { "voice": true }
  }'

Response 202 Accepted:

{
  "success": true,
  "data": {
    "status": "provisioning",
    "phone_number": "+14155550123",
    "transaction_id": "txn_1759740062114_4f9c2a1e",
    "price": 2.5,
    "currency": "USD",
    "credits_debited": 25,
    "remaining_credits": 4175
  }
}

What happens:

1. The wallet is debited immediately.
2. The carrier purchase runs in the background. The response does not include the number's id.
3. Poll GET /phone_numbers until the number appears, then use its id.
4. If the carrier purchase fails, the debit is refunded (ledger type credit_refund_phone_number) and the number never appears in the list.

Requirements:

• Your organization's compliance application must be approved, otherwise 403 compliance_required. Submit it in the dashboard under Settings → Compliance; the error's action_url opens that tab. See api-errors.
• The rental is attributed to the user who created the API key. That user must still be a member of your organization, with an email on record, otherwise 409 api_key_owner_required; create a new key from the dashboard.
• Organizations in proof-of-concept mode use numbers provided by Finn and cannot rent (403 rental_unavailable).

There is no idempotency key. Retrying a rental for the same number doesn't charge you twice: the wallet is debited only once per number for your organization. A retry does record another purchase and start the number's setup again, so check GET /phone_numbers before you retry.

Release a number

DELETE /phone_numbers/{id}

curl -X DELETE "https://api.hirefinn.ai/api/v1/phone_numbers/6b1f0c2e-3d4a-4f5b-9c8d-2e7a1b9f4c03" \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": { "id": "6b1f0c2e-3d4a-4f5b-9c8d-2e7a1b9f4c03", "released": true }
}

Releasing returns the number to the carrier and deletes it from your organization. There is no refund.

The API refuses to release:

• a number used by a deployment that hasn't ended, whether it's the deployment's only number or one of the numbers in its number_pool: 409 number_in_use. Stop the deployment, then release the number.
• a number that has ever been a deployment's phone_number_id, even if that deployment is stopped or completed: 409 number_in_use. Contact Finn support to release it. Parallel deployments (max_parallel_calls above 1) keep their number only in number_pool, so once one of them ends, it no longer blocks the release.
• a number with assignment records, unless you pass force=true: 409 number_in_use.

Errors

Error bodies have the shape { "error": "...", "message": "..." }; internal_error has no message. See api-errors.