Phone numbers

Beta. This endpoint is not final. Field names and response shapes can change before general availability.

Overview

A phone number resource represents a number your workspace controls. Two kinds exist:

Numbers are workspace-scoped. A number is attached to at most one inbound route at a time, and can be used by any number of outbound deployments. For the product behavior behind these fields, read Phone numbers and Inbound routing.

The phone number object

{
  "id": "pn_01HRZ9QK4F8VXG2M",
  "e164": "+14155550142",
  "country": "US",
  "type": "local",
  "source": "rented",
  "status": "active",
  "capabilities": ["voice"],
  "assigned_to": {
    "type": "deployment",
    "id": "dep_01HRZ8B2N7Q1"
  },
  "rented_since": "2026-03-04T09:12:00Z",
  "created_at": "2026-03-04T09:12:00Z"
}

Whether rent amount and currency are exposed on this object is not yet settled. Do not build billing views against a rent field until it appears in the changelog. Wallet and charges are documented in Wallet.

Status values

A number in pending accepts assignment calls, but inbound traffic does not reach your agent until it flips to active. Regulatory review in some countries takes days, not seconds, so do not gate a signup flow on a number reaching active.

List numbers

curl https://api.hirefinn.ai/v1/phone_numbers \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -G \
  -d limit=25 \
  -d status=active \
  -d country=US

Filters: status, country, type, source, and assigned (true or false). Results are paginated per Pagination.

Retrieve a number

curl https://api.hirefinn.ai/v1/phone_numbers/pn_01HRZ9QK4F8VXG2M \
  -H "Authorization: Bearer $FINN_API_KEY"

Search available inventory

Before renting, search what is available. This endpoint returns candidates, not reservations. Another workspace can take a number between your search and your rent call.

curl https://api.hirefinn.ai/v1/phone_numbers/available \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -G \
  -d country=IN \
  -d type=local \
  -d prefix=080

prefix matches the leading digits after the country code. Some countries restrict which prefixes a business may hold, so an empty result set is a normal outcome, not an error.

Rent a number

curl -X POST https://api.hirefinn.ai/v1/phone_numbers \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rent-blr-office-01" \
  -d '{
    "country": "IN",
    "type": "local",
    "e164": "+918041234567"
  }'

Renting charges the workspace wallet and is not free to retry. Always send an Idempotency-Key (see Idempotency). Without one, a network timeout followed by a retry can leave you paying rent on two numbers.

Countries with regulatory requirements reject the rent call until the workspace has an approved compliance record. That returns 409 with an error code naming the missing document. See Compliance.

Assign a number

const res = await fetch(
  "https://api.hirefinn.ai/v1/phone_numbers/pn_01HRZ9QK4F8VXG2M/assign",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FINN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      assigned_to: { type: "deployment", id: "dep_01HRZ8B2N7Q1" },
    }),
  }
);

if (!res.ok) {
  throw new Error(`assign failed: ${res.status} ${await res.text()}`);
}

console.log(await res.json());

Assigning a number that already points somewhere else replaces the existing route without warning. Read the number first if you need to know what you are overwriting. To detach, POST to /unassign with no body.

Release a number

curl -X DELETE https://api.hirefinn.ai/v1/phone_numbers/pn_01HRZ9QK4F8VXG2M \
  -H "Authorization: Bearer $FINN_API_KEY"

Release is not reversible. Once a number leaves your workspace it returns to carrier inventory and you will usually not get the same number back. Callers dialing it after release reach whoever holds it next. Release a number only after the inbound route has been moved.

BYOC numbers cannot be released this way. Remove them at the trunk. See BYOC SIP.

Errors

Full error shapes are in Errors. Rate limits apply per Rate limits.