> ## Documentation Index
> Fetch the complete documentation index at: https://agent-docs.akta.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Best practices for using the List Generation API.

**Resolve industry names to codes before filtering. Never pass free text to** `industry.industry`

The `industry.industry` filter expects akta.pro taxonomy industry codes, not free-text sector names like `"warehouse automation"` or `"fintech"`. Resolve the topic first with the [Industry Search API](/api-reference/supporting-apis/industry-search):

```python theme={null}
industry_code = requests.get(
    "https://api.akta.pro/api/v1/industry/search",
    headers={"x-api-key": API_KEY},
    params={"query": "warehouse automation"}
).json()["data"][0]["code"]

payload = {"filters": {"industry.industry": [industry_code]}}
```

If a topic maps to multiple closely related industries, pass several codes rather than relying on the single top match.

**Use 3-letter ISO country codes for all location filters, not country names**

`location.hq.country`, `location.market_served.markets`, and `location.offices.country` all expect 3-letter ISO alpha-3 codes (`USA`, `IND`, `GBR`), not full country names (`"United States"`). Passing a name instead of a code will not match. `location.hq.city` by contrast, take free text. `location.hq.region` takes [M49 region codes](/region-codes).

```python theme={null}
# ❌ Will not match
"location.hq.country": ["United States"]

# ✅ Correct
"location.hq.country": ["USA"]
```

**Combine filters from multiple groups to narrow results precisely**

Filters from different groups (firmographic, business model, financials, location, technology, funding, and more) can be combined in a single request. All conditions are combined with AND logic — a company must match every specified filter to be included in the results. Layer filters progressively and check `total_count` after each addition to confirm you haven't over-narrowed the list.

**Check `total_count` before paginating**

`total_count` tells you how many companies match your filters in total, capped at 500. Use it to decide whether to paginate with `offset`, or to tighten your filters if the match is too broad to be useful.

***