API Reference

Addresses

Many countries require a verified local address before you can purchase phone numbers there. This multi-step verification workflow submits your address and a supporting document to the carrier for approval.

Countries that require address verification

Netherlands (NL)Germany (DE)France (FR)Italy (IT)Spain (ES)Belgium (BE)Austria (AT)Sweden (SE)Denmark (DK)and more...

Use GET /v1/phone-numbers/countries to get the authoritative list with requires_address flag.

Verification workflow

Check requirements

GET /v1/addresses/requirements?country=NL to see what documents are needed

Create address record

POST /v1/addresses with your name, company, and address details

Upload document

POST /v1/addresses/:id/documents with government ID or business registration

Submit for review

POST /v1/addresses/:id/submit to send to Telnyx for verification (cannot be undone)

Poll for status

POST /v1/addresses/:id/check-status every few minutes until verified

Purchase numbers

GET /v1/phone-numbers/search?country_code=NL -- now returns results

POST/v1/addresses

Required fields: street_address, city, postal_code, country_code, contact_name, contact_email, contact_phone.

curl -X POST https://api.staffifyai.com/v1/addresses \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code":   "NL",
    "contact_name":   "Jan de Vries",
    "contact_email":  "[email protected]",
    "contact_phone":  "+31612345678",
    "company_name":   "Acme BV",
    "street_address": "Keizersgracht 126",
    "city":           "Amsterdam",
    "postal_code":    "1015 CW",
    "city_code":      "020"
  }'

# Response
{ "address_id": 7 }

Field	Required	Description
street_address	required	Street and house number
city	required	City name
postal_code	required	Postal / ZIP code
country_code	required	ISO 3166-1 alpha-2 (e.g. "NL", "DE")
contact_name	required	Full name of the contact person
contact_email	required	Contact email address
contact_phone	required	Contact phone in E.164 format
company_name	optional	Legal company name (required for business verification)
city_code	optional	City dialing code for local presence countries (e.g. "020" for Amsterdam)
address_line_2	optional	Apartment, suite, floor, etc.
state_province	optional	State or province
customer_type	optional	"business" (default) or "individual"
vat_number	optional	VAT registration number
tax_id	optional	Tax ID / EIN
business_website	optional	Company website URL
business_use_case	optional	Description of how numbers will be used

Some countries require additional fields (e.g. cif_number for Spain, siren_number for France, abn_number for Australia). Use GET /v1/addresses/requirements?country=ES to see what is needed.

List and get addresses

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

# Response
{ "addresses": [ { ...address object... } ] }

# GET /v1/addresses/:addressId — single address (includes documents)

Address object (GET /v1/addresses/:addressId)

{
  "address": {
    "id":                  7,
    "street_address":      "Keizersgracht 126",
    "city":                "Amsterdam",
    "postal_code":         "1015 CW",
    "country_code":        "NL",
    "city_code":           "020",
    "contact_name":        "Jan de Vries",
    "contact_email":       "[email protected]",
    "contact_phone":       "+31612345678",
    "company_name":        "Acme BV",
    "verification_status": "verified",
    "number_types": [
      { "number_type": "local", "verification_status": "verified" }
    ],
    "city_name":  "Amsterdam",
    "region":     "North Holland",
    "created_at": "2026-01-10T09:00:00Z",
    "documents": [
      {
        "id":            1,
        "document_type": "company_registration",
        "file_name":     "company-registration.pdf",
        "file_size":     204800,
        "mime_type":     "application/pdf",
        "created_at":    "2026-01-10T09:05:00Z"
      }
    ]
  }
}

POST/v1/addresses/:addressId/documents

Upload a supporting document (government ID, utility bill, business registration). multipart/form-data, field name: document. Accepted formats: PDF, JPEG, PNG (max 10 MB). Optional document_type field (default: proof_of_address). Accepted values: passport_id | company_registration | proof_of_address | vat_certificate | allocation_proof | power_of_attorney | commercial_register | signed_loi

curl -X POST https://api.staffifyai.com/v1/addresses/7/documents \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "document_type=company_registration"

POST/v1/addresses/:addressId/submit

Submission is final and cannot be undone. Verify all details are correct before submitting.

curl -X POST https://api.staffifyai.com/v1/addresses/7/submit \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Status changes to "submitted"

POST/v1/addresses/:addressId/check-status

Sync latest verification status from the carrier. Poll every few minutes after submitting.

curl -X POST https://api.staffifyai.com/v1/addresses/7/check-status \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Response when approved:
{ "verification_status": "verified" }

Status	Meaning
pending	Created, not yet submitted
submitted	Sent to carrier for review
verified	Approved -- you can now purchase numbers
partially_verified	Some number types approved (check requirements)
rejected	Rejected -- fix the issue and resubmit
expired	Verification expired -- resubmit

GET/v1/addresses/requirements?country=NL

Returns the full verification requirements for a country -- which documents are accepted, whether city codes are required, and which number types are supported. Use this before creating an address to know exactly what fields and documents to provide.

curl "https://api.staffifyai.com/v1/addresses/requirements?country=DE" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

Returns 404 if requirements are not defined for the specified country.

GET/v1/addresses/city-codes?country=NL

Get available city codes for a country. Required when purchasing local numbers in NL, DE, ES, BE, PT, PL, or SE.

curl "https://api.staffifyai.com/v1/addresses/city-codes?country=NL" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Response
{
  "city_codes": [
    {
      "city_code":  "020",
      "city_name":  "Amsterdam",
      "region":     "North Holland",
      "is_popular": true
    }
  ]
}

DELETE/v1/addresses/:addressId

Delete an address record. Returns { deleted: true, id }. Cannot delete if the address has active phone numbers linked to it (400).

curl -X DELETE https://api.staffifyai.com/v1/addresses/7 \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Response
{ "deleted": true, "id": 7 }

← Phone Numbers Webhooks (address events) →