Catalog

List territories

List the countries and the regions you can order in.

GETapi.leadity.io/v1/territories

Scope readMCP tool list_territories

Lists every country Leadity holds territory for, whether it is on sale, and its regions (states, provinces, territories, UK regions) with how many areas and ZIP or postal codes each holds. A region's code is what a whole-region selection names in estimate_scrape and create_scrape. Call list_areas for one region's areas and codes.

Example request

curl "https://api.leadity.io/v1/territories" \
  -H "Authorization: Bearer $LEADITY_API_KEY"

Example response

{
  "version": "51be0c93f7aa",
  "countries": [
    {
      "code": "US",
      "orderable": true,
      "states": [
        {
          "code": "TX",
          "areaCount": 1204,
          "zipCount": 1935
        }
      ]
    },
    {
      "code": "CA",
      "orderable": true,
      "states": [
        {
          "code": "ON",
          "areaCount": 214,
          "zipCount": 525
        }
      ]
    },
    {
      "code": "GB",
      "orderable": true,
      "states": [
        {
          "code": "TLI",
          "areaCount": 199,
          "zipCount": 268
        }
      ]
    },
    {
      "code": "AU",
      "orderable": true,
      "states": [
        {
          "code": "NSW",
          "areaCount": 611,
          "zipCount": 611
        }
      ]
    }
  ]
}

Headers

Authorizationstringrequired

Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

Response

versionstringrequired

The territory catalog's content version.

countriesobject[]required

Show child attributes

codestringrequired

The country code, e.g. US.

orderablebooleanrequired

Whether an order may name this country today.

statesobject[]required

Show child attributes

codestringrequired

The region code, e.g. TX.

areaCountintegerrequired

How many areas (cities and towns) the region holds.

zipCountintegerrequired

How many ZIP or postal codes the region holds.

Errors

Every refusal answers { error, message } with the status below. The full list is on the Errors page.

Code	Status	Meaning	Extra fields
unauthorized	401	The API key is missing, malformed, revoked or expired.	-
wrong_key_kind	401	This key opens the other surface: an API key works on the HTTP API, an MCP key on the MCP server.	-
account_suspended	403	The account is suspended.	-
email_not_verified	403	The account's email address is not verified yet.	-
rate_limited	429	Too many requests. Wait for the Retry-After seconds and try again.	`retryAfterSeconds`: The seconds to wait, the same number as the Retry-After header.
try_again	503	Leadity could not answer just now. Retry in a moment, with the same Idempotency-Key on a spending call.	`retryAfterSeconds`: When a request with this Idempotency-Key is still being processed: the seconds to wait before retrying with the same key, as the Retry-After header says.
internal_error	500	Something failed on our side. Nothing was charged twice.	`body`: On the MCP server, when Leadity answered in a shape the tool does not publish: that answer as it came.