Filtering - The Data City

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

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.
`AllowLargeAnalysis`	`boolean`	Required when filtering against a large uploaded set.

The full filter shape is documented on the POST /v2/companies reference page — these are the most common starting points.

Pairing with `insights`

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

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

{
  "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

{
  "returnCount": 1000,
  "CompanyNumberSetId": "set_abc123",
  "AllowLargeAnalysis": true
}

Upload the set first (see 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.

​Minimal request

​Core filter fields

​Pairing with insights

​Patterns

​Filter a portfolio you already have

​Use a large uploaded set

​Available filters

​Pagination