API Reference

Phone Numbers

Search available numbers, purchase them, and assign them to agents. Numbers cost EUR 5 per 4-week billing cycle each (not a calendar month -- billed every 28 days from the purchase date). Many countries require address verification before purchase.

Many countries (Netherlands, Germany, France, UK, etc.) require a verified local address before you can purchase numbers there. See the Addresses guide for the verification workflow.

GET/v1/phone-numbers/search

Search available numbers to purchase.

Param	Default	Description
country_code	US	ISO 3166-1 alpha-2 country code
type	local	local \| mobile \| toll_free
area_code	—	US/CA area code filter (e.g. "415")
city_code	—	EU city code filter (e.g. "020" for Amsterdam)
contains	—	Filter numbers containing this digit string
limit	20	Results per page (max 100)

# Amsterdam local number
curl "https://api.staffifyai.com/v1/phone-numbers/search?country_code=NL&city_code=020" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# US San Francisco area
curl "https://api.staffifyai.com/v1/phone-numbers/search?country_code=US&area_code=415" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# US toll-free
curl "https://api.staffifyai.com/v1/phone-numbers/search?country_code=US&type=toll_free" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

POST/v1/phone-numbers

Purchase a number from the search results.

Param	Type	Required	Description
phone_number	string	required	The exact number from search results (E.164 format)
country_code	string	optional	Country code (default: "US")
number_type	string	optional	"local", "mobile", or "toll_free" (default: "local")
address_id	integer	optional	Required for all non-US/CA countries. Must be a verified (or partially_verified) address ID belonging to your org.
city_code	string	optional	Required for countries with local presence rules (DE, ES, etc.) when purchasing local numbers. Must match the city_code of your verified address.

Requires a minimum balance of EUR 5.00 in your account. Returns 402 if balance is insufficient. For US/CA numbers, your organization must also have at least one verified address on file before purchasing.

# Purchase a Netherlands number (requires verified address + city_code)
curl -X POST https://api.staffifyai.com/v1/phone-numbers \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+31204567890",
    "country_code": "NL",
    "number_type":  "local",
    "address_id":   7,
    "city_code":    "020"
  }'

# Purchase a US number (no address_id needed)
curl -X POST https://api.staffifyai.com/v1/phone-numbers \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

# Response
{ "success": true, "id": 42, "phone_number": "+14155551234" }

PUT/v1/phone-numbers/:numberId/assign

Assign an owned number to an agent. Both the agent and the number must belong to your organization. Replaces any existing assignment (no 409 on re-assign).

curl -X PUT https://api.staffifyai.com/v1/phone-numbers/42/assign \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": 123 }'

# Response
{ "success": true, "phone_number_id": 42, "agent_id": 123 }

# Unassign (DELETE same path, no body) — returns 204 No Content
# Returns 409 if no agent is currently assigned
curl -X DELETE https://api.staffifyai.com/v1/phone-numbers/42/assign \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

GET/v1/phone-numbers/countries

List all supported countries and whether they require address verification.

curl "https://api.staffifyai.com/v1/phone-numbers/countries" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Response
{
  "countries": [
    { "code": "US", "name": "United States", "requires_address": false },
    { "code": "NL", "name": "Netherlands",   "requires_address": true  },
    { "code": "DE", "name": "Germany",       "requires_address": true  }
  ]
}

The phone number object

{
  "id":           42,
  "phone_number": "+31850012345",
  "status":       "active",
  "agent_id":     123,
  "agent_name":   "Support Bot",
  "tags":         ["support", "amsterdam"]
}

status values: active | pending_release.

Other endpoints

# List owned numbers
curl "https://api.staffifyai.com/v1/phone-numbers" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Get a single number
curl "https://api.staffifyai.com/v1/phone-numbers/42" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Release a number
curl -X DELETE https://api.staffifyai.com/v1/phone-numbers/42 \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

GET

/v1/phone-numbers

List owned numbers. Query params: after (cursor ID), limit (default 20, max 100). Returns { phone_numbers: [...], next_cursor }.

GET

/v1/phone-numbers/:numberId

Get a single owned number.

PATCH

/v1/phone-numbers/:numberId

Update tags: { "tags": ["support", "sales"] }. Tags must be an array of strings. Max 20 tags, each max 50 characters.

DELETE

/v1/phone-numbers/:numberId

Release a number. Must be active and have no agent assigned (unassign first). Response: { pending_release: true, id: ..., reclaim_before: "ISO timestamp" } — not immediate deletion; enters a 7-day reclaim window.

POST

/v1/phone-numbers/:numberId/reclaim

Reclaim a released number. Only works while status is pending_release. Window: 7 days after release. Returns { reclaimed: true, id: ..., status: "active" }.

Addresses (verification) →Agents →