> ## 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. # Filter companies > Returns filtered companies and aggregations as host-defined JSON. ## OpenAPI ````yaml /global-api/de.openapi.json post /v1/de/companies openapi: 3.1.0 info: title: The Data City — Germany company data description: >- Company data for Germany, served through The Data City public API gateway. Authenticate with an API key as a bearer token. Rate limit is 60 requests per minute per key. Call GET /v1/de/filters before filtering: sector codes and location values cannot be guessed, and an unrecognised value returns an empty result rather than an error. termsOfService: https://thedatacity.com/terms-and-conditions/ contact: name: The Data City email: hello@thedatacity.com version: v1 servers: - url: https://global-api.thedatacity.com description: Production security: - ApiKey: [] tags: - name: Companies - name: Search - name: Filters - name: Lookups - name: Classification - name: Metadata paths: /v1/de/companies: post: tags: - Companies summary: Filter companies description: Returns filtered companies and aggregations as host-defined JSON. operationId: de_post_companies requestBody: content: application/json: schema: $ref: '#/components/schemas/CompanyFilters' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FilteredCompanies' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '401': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: No API key was supplied, or it is not valid for this environment. '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '429': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- Rate limit exceeded — 60 requests per minute per key. The retry-after header gives the number of seconds to wait. headers: retry-after: description: Seconds to wait before retrying. schema: type: integer '500': description: Internal Server Error components: schemas: CompanyFilters: type: object properties: WZs: type: array items: type: string description: >- Filter by primary industry scheme codes (wire name set at scaffold time). nullable: true Name: maxLength: 500 minLength: 0 type: string description: >- Filter by company name prefix, company number, Handelsregister number (`OrgNumber` / `RegistrationNumber`), VAT number (`VATNumber`), or website. Domain-style needles (keep dots) match `Website` exactly or as a subdomain suffix; other needles still substring-match website via `contains`. nullable: true Country: maxLength: 100 minLength: 0 type: string description: Filter by country nullable: true EmployeeRange: maxLength: 20 minLength: 0 type: string description: >- Filter by employee-range slug from `GET /api/filters` (`employeeRanges[].id`). Matches DuckDB `EmployeesBand` via URL-safe slug (API key `EmployeeRange`). nullable: true LegalForm: maxLength: 150 minLength: 0 type: string description: >- Filter by legal form slug from `GET /api/filters` (`legalForms[].id`). nullable: true LegalForms: maxItems: 100 type: array items: type: string description: >- Filter by one or more legal form slugs from `GET /api/filters` (`legalForms[].id`). Matches any listed form (OR). nullable: true HQPostcode: maxLength: 10 minLength: 0 pattern: ^[0-9]{5}$ type: string description: Filter by headquarters postal code nullable: true HQAddress: maxLength: 500 minLength: 0 type: string description: Filter by headquarters address substring (case-insensitive). nullable: true DateOfIncorporation: type: string description: Filter by date of incorporation (exact match) format: date nullable: true IncorporationDateFrom: type: string description: Filter by minimum date of incorporation (inclusive) format: date nullable: true IncorporationDateTo: type: string description: Filter by maximum date of incorporation (inclusive) format: date nullable: true HasWebsite: type: boolean description: Filter companies that have a website nullable: true OperatingLocationAddresses: maxItems: 20 type: array items: type: string description: Filter by operating location addresses (partial match) nullable: true MinTurnover: maximum: 9223372036854776000 minimum: 0 type: integer description: Minimum annual turnover value format: int64 nullable: true MaxTurnover: maximum: 9223372036854776000 minimum: 0 type: integer description: Maximum annual turnover value format: int64 nullable: true MinEBIT: maximum: 9223372036854776000 minimum: -9223372036854776000 type: integer description: Minimum EBIT (Earnings Before Interest and Taxes) value format: int64 nullable: true MaxEBIT: maximum: 9223372036854776000 minimum: -9223372036854776000 type: integer description: Maximum EBIT (Earnings Before Interest and Taxes) value format: int64 nullable: true MinNetIncome: maximum: 9223372036854776000 minimum: -9223372036854776000 type: integer description: Minimum net income value format: int64 nullable: true MaxNetIncome: maximum: 9223372036854776000 minimum: -9223372036854776000 type: integer description: Maximum net income value format: int64 nullable: true FinancialYearEnding: type: integer description: Filter by specific financial year ending format: int32 nullable: true MinFinancialYearEnding: type: integer description: Minimum financial year ending format: int32 nullable: true MaxFinancialYearEnding: type: integer description: Maximum financial year ending format: int32 nullable: true AccountsType: maxLength: 50 minLength: 0 type: string description: Filter by accounts type (e.g., "Full", "Abbreviated", "Small") nullable: true RTICs: type: array items: type: string description: >- Filter by RTIC codes. Matches companies that have any of the specified RTIC codes. nullable: true RWZs: type: array items: type: string description: >- Filter by secondary industry scheme codes (wire name set at scaffold time). nullable: true State: maxItems: 100 type: array items: type: string description: >- Filter by Bundesland slug or name from `GET /api/filters` (`states[].id` / `states[].name`). Matches `HQPostcodeDetails.County`. nullable: true Zipcode: maxItems: 100 type: array items: type: string description: >- Filter by headquarters postal code(s) (5-digit German PLZ). Same column as TDC_Global_Server_API_DE.Models.Filtering.Filters.HQPostcode. nullable: true Town: maxItems: 1000 type: array items: type: string description: >- Filter by town / PostTown from `HQPostcodeDetails.PostTown` (case-insensitive). nullable: true Director: $ref: '#/components/schemas/DirectorFilterCriteria' LowerLatitude: maximum: 90 minimum: -90 type: number description: >- South edge of a geographic bounding box (minimum latitude), inclusive. WGS-84 decimal degrees. format: double nullable: true UpperLatitude: maximum: 90 minimum: -90 type: number description: >- North edge of a geographic bounding box (maximum latitude), inclusive. WGS-84 decimal degrees. format: double nullable: true LowerLongitude: maximum: 180 minimum: -180 type: number description: >- West edge of a geographic bounding box (minimum longitude), inclusive. WGS-84 decimal degrees. format: double nullable: true UpperLongitude: maximum: 180 minimum: -180 type: number description: >- East edge of a geographic bounding box (maximum longitude), inclusive. WGS-84 decimal degrees. format: double nullable: true HasWebText: type: boolean description: Filter by companies that have web text nullable: true Includes: maxItems: 5000 type: array items: type: string description: >- Restrict results to these company numbers (`CompanyNumber IN (...)`). nullable: true Excludes: maxItems: 5000 type: array items: type: string description: Exclude these company numbers (`CompanyNumber NOT IN (...)`). nullable: true WebTextPositiveKeywords: maxItems: 25 type: array items: type: string description: >- Positive keywords matched against web text (BM25 when FTS index exists; otherwise ILIKE). nullable: true WebTextPositiveKeywordsOperator: pattern: ^(AND|OR)$ type: string description: 'Combines positive keywords: AND (all) or OR (any).' nullable: true WebTextPositiveKeywordsMode: pattern: ^(AND|OR)$ type: string description: >- Backward-compatible alias for TDC_Global_Server_API_DE.Models.Filtering.Filters.WebTextPositiveKeywordsOperator. nullable: true deprecated: true WebTextNegativeKeywords: maxItems: 25 type: array items: type: string description: 'Negative keywords: rows matching these are excluded.' nullable: true WebTextNegativeKeywordsOperator: pattern: ^(AND|OR)$ type: string description: Combines negative keyword checks inside NOT (...). nullable: true WebTextNegativeKeywordsMode: pattern: ^(AND|OR)$ type: string description: >- Backward-compatible alias for TDC_Global_Server_API_DE.Models.Filtering.Filters.WebTextNegativeKeywordsOperator. nullable: true deprecated: true IncludeInsights: type: boolean description: >- When false, skips insight bucket aggregation. Omit or null for default (include insights). nullable: true IncludeTotalCount: type: boolean description: >- When false, skips total-count queries and omits `TotalCount` from the response. Omit or null for default (include total count). nullable: true IncludesLocations: type: boolean description: >- When true, nested location lists are loaded on each company. Omit or null for default (omit lists). Limit: maximum: 1000 minimum: 1 type: integer description: >- Maximum number of results to return (uses QueryConstants.MaxQueryLimit) format: int32 nullable: true Offset: maximum: 2147483647 minimum: 0 type: integer description: 'Number of results to skip for pagination (default: 0)' format: int32 nullable: true SortBy: maxItems: 10 type: array items: $ref: '#/components/schemas/SortOption' description: Sort options for the results nullable: true additionalProperties: false description: Request model for filtering companies with comprehensive search criteria FilteredCompanies: required: - Companies type: object properties: Companies: type: array items: $ref: '#/components/schemas/ProcessedCompany' description: List of companies matching the filter criteria nullable: true Insights: $ref: '#/components/schemas/Insights' TotalCount: type: integer description: >- Total number of companies matching the filter criteria (before pagination). Omitted when not requested. format: int32 nullable: true additionalProperties: false description: >- Response model containing filtered companies with pagination and insights ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} Problem: type: object description: Error response, following RFC 9457 (problem details for HTTP APIs). properties: type: type: string description: URI identifying the problem type. title: type: string description: Short, human-readable summary. status: type: integer description: HTTP status code. detail: type: string description: Explanation specific to this occurrence. instance: type: string description: The path that produced the error. DirectorFilterCriteria: type: object properties: LocalPnr: maxLength: 500 minLength: 0 type: string description: Exact local personal number (DE DuckDB `local_pnr`). nullable: true FirstName: maxLength: 500 minLength: 0 type: string description: First-name prefix (case-insensitive). nullable: true LastName: maxLength: 500 minLength: 0 type: string description: Last-name prefix (case-insensitive). nullable: true DateOfBirth: type: string description: Exact date of birth (DE DuckDB `date_of_birth`). format: date nullable: true FullName: maxLength: 500 minLength: 0 type: string description: Full-name prefix (case-insensitive; US DuckDB `FullName`). nullable: true additionalProperties: false description: >- Optional director filter values for `POST /api/companies` (`Director`) and M:TDC_Global_Server_API_Core.Classes.Configuration.DirectorFilterSql.Build(TDC_Global_Server_API_Core.Classes.Configuration.DirectorFilterCriteria,TDC_Global_Server_API_Core.Classes.Configuration.DirectorFilterProfile,System.String,System.String). SortOption: required: - Direction - Field type: object properties: Field: maxLength: 50 minLength: 0 type: string description: Column or logical field name to sort by. Direction: minLength: 1 pattern: ^(ASC|DESC)$ type: string description: '`ASC` or `DESC`.' additionalProperties: false description: Sort option for ordering query results. ProcessedCompany: required: - CompanyNumber type: object properties: Description: type: string description: Company description or business activity summary nullable: true LegalForm: type: string description: Legal form of the company nullable: true EmployeeRange: type: string description: Employee count range bucket label nullable: true RTICs: type: array items: $ref: '#/components/schemas/RTIC' description: >- Real-Time Industrial Classifications (RTIC) associated with the company. nullable: true LogoURL: type: string description: URL of the company logo nullable: true ScreenshotURL: type: string description: URL of the company screenshot nullable: true OperatingLocationsCount: type: integer description: >- Number of operating or group locations stored on the company row (without returning the full list). format: int32 nullable: true CompanyNumber: minLength: 1 type: string description: Unique company identifier from the data source Name: type: string description: Official company name nullable: true Website: type: string nullable: true Country: type: string description: Country where the company is registered. nullable: true OrgNumber: type: string description: >- Handelsregister number from Creditsafe (`org_number`). Prefer this for UI display and website verification. Not unique without a court qualifier. nullable: true RegistrationNumber: type: string description: Handelsregister number from Creditsafe (`reg_number`). nullable: true VATNumber: type: string description: German VAT identification number from Creditsafe (`vat_number`). nullable: true HQAddress: type: string description: Headquarters address nullable: true HQPostcode: type: string description: Headquarters postal code nullable: true HQPostcodeDetails: $ref: '#/components/schemas/CompanyAddress' Address: type: string description: Street address of the company headquarters nullable: true Town: type: string description: City or town where the company is located nullable: true State: type: string description: State where the company is registered nullable: true Phone: type: string description: Primary business phone number nullable: true Zipcode: type: string description: Postal code for the company nullable: true Latitude: type: number description: Latitude of the company format: double nullable: true Longitude: type: number description: Longitude of the company format: double nullable: true DateOfIncorporation: type: string description: Date when the company was incorporated format: date nullable: true BestEstimateCurrentEmployees: type: integer description: Best estimate of current employees from source enrichment. format: int32 nullable: true BestEstimateCurrentTurnover: type: number description: Best estimate of current turnover from source enrichment. format: double nullable: true Turnover: type: integer description: >- Annual revenue/turnover value (materialised in DuckDB from Creditsafe latest turnover / finances). format: int64 nullable: true TurnoverBand: type: string description: Turnover band label for bucketing/reporting. nullable: true BestEstimateGrowthPercentagePerYear: type: number description: Best estimate growth percentage per year. format: double nullable: true FinancesByYear: type: array items: $ref: '#/components/schemas/GermanFinances' description: Annual financial snapshots for this company. nullable: true Directors: type: array items: $ref: '#/components/schemas/GermanCompanyDirector' description: >- Directors associated with this company (German Creditsafe shape: shared fields plus address). nullable: true CompanyGrowthTrends: type: string description: Company growth trend classification label/value. nullable: true WZs: type: array items: type: string description: Primary industry classification rows associated with the company nullable: true RWZs: type: array items: $ref: '#/components/schemas/RWZ' description: Secondary industry classification rows associated with the company nullable: true OECDScaleup: type: boolean description: OECD scaleup indicator. SimilarCompanies: type: array items: $ref: '#/components/schemas/SimilarCompany' description: Similar companies to the current company nullable: true additionalProperties: false description: Processed company data with comprehensive business information Insights: type: object properties: EmployeeRanges: type: array items: $ref: '#/components/schemas/IDNameCount' description: Distribution of employee ranges in the filtered results nullable: true LegalForms: type: array items: $ref: '#/components/schemas/IDNameCount' description: Distribution of legal forms in the filtered results nullable: true IncorporationDates: type: array items: $ref: '#/components/schemas/IDNameCount' description: Distribution of incorporation dates in the filtered results nullable: true RTICs: type: array items: $ref: '#/components/schemas/IDNameCount' description: >- Distribution of Real-Time Industrial Classifications (RTIC) in the filtered results. nullable: true WZs: type: array items: $ref: '#/components/schemas/IDNameCount' description: Distribution of primary industry codes in the filtered results nullable: true Turnover: type: array items: $ref: '#/components/schemas/IDNameCount' description: Distribution of turnover amounts in the filtered results nullable: true States: type: array items: $ref: '#/components/schemas/IDNameCount' description: Distribution of states in the filtered results nullable: true RWZs: type: array items: $ref: '#/components/schemas/IDNameCount' description: Distribution of secondary industry codes in the filtered results nullable: true additionalProperties: false description: Aggregated insights about filtered company data RTIC: type: object properties: CompanyNumber: type: string description: >- Company identifier (RTIC parquet key column, aliased to `CompanyNumber` in SQL). nullable: true SectorCode: type: string description: RTIC sector code. nullable: true SectorName: type: string description: RTIC sector name. nullable: true VerticalCode: type: string description: RTIC vertical code. nullable: true VerticalName: type: string description: RTIC vertical name. nullable: true Score: type: number description: Classification score from the RTIC model. format: double nullable: true WordsMatched: type: integer description: Number of words matched when classifying. format: int32 nullable: true Name: type: string description: Optional display name (when present in source data). nullable: true additionalProperties: false description: >- Real-Time Industrial Classifications (RTIC) row. Parquet company id is selected as TDC_Global_Server_API_Core.Models.RTIC.CompanyNumber (see TDC_Global_Server_API_Core.Services.RTICService). JSON uses the property name `CompanyNumber`; country hosts may use different JSON names for the root company identifier (e.g. France exposes `Siren` on the company payload). CompanyAddress: type: object properties: DepartmentName: type: string description: The name of the department nullable: true OrganisationName: type: string description: The name of the organisation nullable: true SubBuildingName: type: string description: The name of the sub-building nullable: true BuildingName: type: string description: The name of the building nullable: true POBoxNumber: type: string description: The number of the PO box nullable: true BuildingNumber: type: string description: The number of the building nullable: true BuildingGroup: type: string description: The group of the building nullable: true DependentStreet: type: string description: The dependent street nullable: true MainStreet: type: string description: The main street nullable: true DoubleDependentLocality: type: string description: The double dependent locality nullable: true DependentLocality: type: string description: The dependent locality nullable: true PostTown: type: string description: The post town nullable: true County: type: string description: The county nullable: true Postcode: type: string description: The postcode nullable: true Latitude: type: number description: The latitude format: double nullable: true Longitude: type: number description: The longitude format: double nullable: true additionalProperties: false description: Model representing a Germany address GermanFinances: type: object properties: CompanyRegistrationNumber: type: string description: Company registration number. nullable: true FinancialYear: type: string description: Financial year end date. format: date nullable: true ProfitBeforeTax: type: number description: Profit before tax. format: double nullable: true ProfitAfterTax: type: number description: Profit after tax. format: double nullable: true NetWorth: type: number description: Net worth. format: double nullable: true WorkingCapital: type: number description: Working capital. format: double nullable: true Revenue: type: number description: Revenue. format: double nullable: true TotalFixedAssets: type: number description: Total fixed assets. format: double nullable: true TotalCurrentAssets: type: number description: Total current assets. format: double nullable: true TotalCurrentLiabilities: type: number description: Total current liabilities. format: double nullable: true TotalLongTermLiabilities: type: number description: Total long-term liabilities. format: double nullable: true TotalLiabilities: type: number description: Total liabilities. format: double nullable: true TotalShareholdersEquity: type: number description: Total shareholders' equity. format: double nullable: true ConsolidatedAccounts: type: boolean description: >- Whether these figures are consolidated accounts (`Y` in source → `true`). Employees: type: integer description: Number of employees. format: int32 nullable: true Turnover: type: number description: Turnover. format: double nullable: true TotalAssets: type: number description: Total assets. format: double nullable: true additionalProperties: false description: >- Represents financial data for German companies from CreditSafe (CSKF01). CLR and API wire names are PascalCase; DuckDB STRUCT JSON remains snake_case (TDC_Global_Server_API_DE.Utilities.GermanFinancesJsonConverter). GermanCompanyDirector: type: object properties: FirstName: type: string description: Director or executive first name. nullable: true LastName: type: string description: Director or executive last name. nullable: true FullName: type: string description: Full display name when the source provides one (e.g. Infobel). nullable: true LocalPnr: type: string description: Local personal number / national id when available (e.g. DE PNR). nullable: true DateOfBirth: type: string description: Date of birth when available. format: date nullable: true DateOfChange: type: string description: Date the director record last changed when the source provides it. format: date nullable: true Active: type: boolean description: Whether the appointment is active when the source provides status. nullable: true Position: type: string description: Job title / position when available. nullable: true Gender: type: string description: Gender when available. nullable: true Language: type: string description: Language preference when available. nullable: true EntityCountryCode: type: string description: Entity country code. nullable: true CountryCode: type: string description: Country code. nullable: true City: type: string description: City. nullable: true Zip: type: string description: ZIP/postal code. nullable: true StreetHouseNumber: type: string description: Street and house number. nullable: true Address2: type: string description: Second address line. nullable: true additionalProperties: false description: >- German company director: shared TDC_Global_Server_API_Core.Models.CompanyDirector fields plus Creditsafe address. RWZ: type: object properties: CompanyNumber: type: string description: Unique Company Number for the company nullable: true Code: type: string description: Code aligned with a primary industry code nullable: true Name: type: string description: Name/description from the primary code dictionary when enriched nullable: true Score: type: number description: >- Score indicating the relevance or match strength of this classification format: double nullable: true additionalProperties: false description: >- Model representing TDC_Global_Server_API_DE.Models.RWZ (secondary industry classification) rows. TDC_Global_Server_API_DE.Models.RWZ.Code aligns with a primary WZs code; data lives in a separate parquet file. SimilarCompany: required: - CompanyNumber - SimilarityScore type: object properties: CompanyNumber: type: string description: >- The similar company identifier (host-specific format, e.g. SIREN or US company number). nullable: true SimilarityScore: type: number description: Similarity score for this pair. format: double additionalProperties: false description: Represents a similarity score between two companies. IDNameCount: required: - ID type: object properties: ID: type: string description: Stable identifier (code or bucket key). nullable: true Name: type: string description: Human-readable label. nullable: true Count: type: integer description: Occurrence count when applicable. format: int32 nullable: true Children: type: array items: $ref: '#/components/schemas/IDNameCount' description: Child nodes for hierarchical classifications. nullable: true additionalProperties: false description: >- Hierarchical filter or bucket item with optional child nodes (NAF/NAIC trees, score bands, etc.). securitySchemes: ApiKey: type: http scheme: bearer description: >- An API key issued by The Data City, sent as: Authorization: Bearer YOUR_KEY ````