> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List territories

> List the countries and the regions you can order in.

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.

`GET https://api.leadity.io/v1/territories`

- Scope: `read`
- Spends credits: no
- MCP tool: `list_territories`

## Headers

- `Authorization`, string, required. Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

## Example request

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

```javascript Node.js
const response = await fetch("https://api.leadity.io/v1/territories", {
  headers: {
    Authorization: `Bearer ${process.env.LEADITY_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
```

```python Python
import os

import requests

response = requests.get(
    "https://api.leadity.io/v1/territories",
    headers={
        "Authorization": f"Bearer {os.environ['LEADITY_API_KEY']}",
    },
)

print(response.json())
```

## Response

- `version`, string, required. The territory catalog's content version.
- `countries`, object[], required.
  - `code`, string, required. The country code, e.g. US.
  - `orderable`, boolean, required. Whether an order may name this country today.
  - `states`, object[], required.
    - `code`, string, required. The region code, e.g. TX.
    - `areaCount`, integer, required. How many areas (cities and towns) the region holds.
    - `zipCount`, integer, required. How many ZIP or postal codes the region holds.

## Example response

```json 200
{
  "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
        }
      ]
    }
  ]
}
```

## Errors

Every refusal answers `{ error, message }` with the status below. The full list is on the [Errors](https://docs.leadity.io/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. |