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

# Filtering

> Build a list of companies that match your criteria — RTICs, CICs, or your own portfolio.

The `POST /v2/companies` endpoint takes a JSON body describing which companies you want and returns the matching list. It's the workhorse of most integrations.

## Minimal request

```bash theme={null}
curl -X POST 'https://product-api.thedatacity.com/api/v2/companies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "returnCount": 20,
        "rtics": ["RTIC-12345"]
      }'
```

This returns the first 20 companies classified under RTIC `RTIC-12345`.

## Core filter fields

| Field                | Type       | Purpose                                                                                                                         |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `rtics`              | `string[]` | Selected RTIC codes. Companies matching **any** of the listed RTICs are returned.                                               |
| `cics`               | `string[]` | User-defined Custom Industrial Classification codes.                                                                            |
| `CompanyNumbers`     | `string[]` | Inline UK Companies House numbers. Use for portfolios up to roughly 50k entries.                                                |
| `CompanyNumberSetId` | `string`   | An uploaded set ID — use instead of `CompanyNumbers` for very large portfolios. See [Batching](/api-reference/guides/batching). |
| `AllowLargeAnalysis` | `boolean`  | Required when filtering against a large uploaded set.                                                                           |

The full filter shape is documented on the [`POST /v2/companies` reference page](/api-reference) — these are the most common starting points.

## Pairing with `insights`

Add `?insights=true` to get dashboard-style aggregations alongside the company rows:

```bash theme={null}
curl -X POST 'https://product-api.thedatacity.com/api/v2/companies?insights=true' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"returnCount": 20, "rtics": ["RTIC-12345"]}'
```

Aggregations are computed over the **full matched set**, not just the page. That means you can keep `returnCount` small on the first call to grab the insights cheaply.

## Patterns

### Filter a portfolio you already have

```json theme={null}
{
  "returnCount": 1000,
  "CompanyNumbers": ["12345678", "87654321", "11223344"],
  "rtics": ["RTIC-12345"]
}
```

Restricts results to the intersection of your portfolio and the RTIC.

### Use a large uploaded set

```json theme={null}
{
  "returnCount": 1000,
  "CompanyNumberSetId": "set_abc123",
  "AllowLargeAnalysis": true
}
```

Upload the set first (see [Batching](/api-reference/guides/batching)), then filter against the `setId`. Don't combine `CompanyNumberSetId` with `CompanyNumbers` — the set wins.

## Available filters

`GET /v2/filters` returns the catalogue of filter codes (RTICs, sectors, etc.) currently available. Call it once at startup, cache the result, and use the codes in your `POST /v2/companies` body.

## Pagination

Filter responses paginate with `returnCount` and `skip`. See [Pagination](/api-reference/guides/pagination).

<Snippet file="need-help.mdx" />