{
  "service": "carrier",
  "title": "Carrier Lookup API",
  "description": "Who serves a phone number: carrier, line type, place.",
  "endpoints": {
    "lookup": "GET /carrier/{number}"
  },
  "examples": {
    "lookup": "/carrier/+14155552671",
    "national": "/carrier/07712345678?country=GB"
  },
  "response": {
    "phone": "Normalized number (+ country code, no spaces), or null if invalid",
    "valid": "Number is valid",
    "country": "ISO 3166-1 alpha-2 country",
    "type": "mobile | landline | voip | toll_free | unknown",
    "carrier": "Carrier display name, else null",
    "burner": "Carrier is a known burner number app (TextNow, Pinger class), null when carrier is unknown",
    "city": "City where the number block was issued (not live location), else null",
    "state": "State/province code from the area code (NANP), else null",
    "state_name": "State/province name from the area code (NANP), else null"
  },
  "parameters": {
    "country": "?country=GB → Optional. Needed for national numbers outside North America"
  },
  "tips": [
    "voip is the type the numbering plan cannot see — the network dip catches it",
    "Every lookup on a valid number uses one carrier unit (monthly quota per plan)",
    "Free syntax checks and formatting live on /phone, no unit spent"
  ]
}