> ## 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.

# Classify companies

> Runs the classification pipeline for the posted filter and training payload.



## OpenAPI

````yaml /global-api/ie.openapi.json post /v1/ie/classification
openapi: 3.1.0
info:
  title: The Data City — Ireland company data
  description: >-
    Company data for Ireland, 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/ie/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/ie/classification:
    post:
      tags:
        - Classification
      summary: Classify companies
      description: >-
        Runs the classification pipeline for the posted filter and training
        payload.
      operationId: ie_post_classification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassificationFilters'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyCompaniesReturnObject'
        '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.
        '404':
          description: Not Found
          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:
    ClassificationFilters:
      type: object
      properties:
        NACEs:
          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 (partial match)
          nullable: true
        Country:
          maxLength: 100
          minLength: 0
          type: string
          description: Filter by country
          nullable: true
        LegalForm:
          maxLength: 150
          minLength: 0
          type: string
          description: >-
            Filter by legal form (e.g., "Corporation", "LLC", "Partnership",
            "Sole Proprietorship")
          nullable: true
        LegalForms:
          maxItems: 100
          type: array
          items:
            type: string
          description: >-
            Filter by one or more legal forms 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
        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
        RNACEs:
          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 state
          nullable: true
        Zipcode:
          maxItems: 100
          type: array
          items:
            type: string
          description: Filter by zipcode
          nullable: true
        Town:
          maxItems: 1000
          type: array
          items:
            type: string
          description: Filter by town
          nullable: true
        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_IE.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_IE.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
        Cutoff:
          type: number
          description: >-
            Minimum raw classifier score (bias + weighted terms), not a
            percentage.
          format: double
          nullable: true
        'Yes':
          type: array
          items:
            type: string
          description: List of company numbers to include in the classification
          nullable: true
        'No':
          type: array
          items:
            type: string
          description: List of company numbers to exclude from the classification
          nullable: true
        VerticalSeed:
          type: string
          description: >-
            Optional RTIC vertical code whose training rows are loaded from the
            vertical seed parquet.
          nullable: true
        UseTranslatedWebTextForYesNo:
          type: boolean
          description: >-
            When true, adds translated web-text training rows for
            TDC_Global_Server_API_IE.Models.Filtering.ClassificationFilters.Yes
            and
            TDC_Global_Server_API_IE.Models.Filtering.ClassificationFilters.No

            companies. When omitted, uses the host default.
          nullable: true
        VerticalSeedNativeLanguageOnly:
          type: boolean
          description: >-
            When true, vertical seed uses only the host native language, not
            English.
        ManuallyInclude:
          type: array
          items:
            type: string
          description: List of company numbers to manually include in the classification
          nullable: true
        ManuallyExclude:
          type: array
          items:
            type: string
          description: List of company numbers to manually exclude from the classification
          nullable: true
      additionalProperties: false
      description: Request model for filtering companies with comprehensive search criteria
    ClassifyCompaniesReturnObject:
      type: object
      properties:
        Status:
          $ref: '#/components/schemas/Status'
        CompaniesAboveCutoff:
          type: integer
          description: Count of companies scoring strictly above the cutoff.
          format: int64
        CompaniesAboveCutoffMatchingFilters:
          type: integer
          description: Count of those companies that also match active filters.
          format: int64
        ModelCode:
          type: string
          description: Classifier model identifier.
          nullable: true
        WordScores:
          type: array
          items:
            $ref: '#/components/schemas/ModelWordScore'
          description: Trained classifier vocabulary weights (linear model coefficients).
          nullable: true
        ScoreDistribution:
          type: array
          items:
            $ref: '#/components/schemas/IDNameCount'
          description: Histogram of scores across the candidate set.
          nullable: true
        Results:
          type: array
          items:
            $ref: '#/components/schemas/Results'
          description: Per-company classification results.
          nullable: true
      additionalProperties: false
      description: >-
        Complete classification API payload (host chooses <typeparamref
        name="TResults" /> for JSON shape, e.g. Siren vs company number).
    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.
    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.
    Status:
      type: object
      properties:
        Message:
          type: string
          description: Status or error message.
          nullable: true
        ModelCode:
          type: string
          description: Model code for this run.
          nullable: true
        WordsWithNonZeroWeightsInClassifier:
          type: integer
          description: Words with non-zero weights in the classifier.
          format: int32
        SecondsSpentGettingTrainingData:
          type: number
          description: Seconds spent loading training web text.
          format: double
        SecondsSpentTranslatingYesNoWebText:
          type: number
          description: >-
            Seconds spent on Mistral Yes/No web-text translation (0 when
            translation is disabled or fully cached).
          format: double
        SecondsSpentTrainingClassifier:
          type: number
          description: Seconds spent training the classifier.
          format: double
        SecondsSpentClassifying:
          type: number
          description: Seconds spent scoring companies.
          format: double
        SecondsSpentSavingClassificationResults:
          type: number
          description: Seconds spent persisting scores.
          format: double
        SecondsSpentGettingCompanyDetails:
          type: number
          description: Seconds spent loading company details for the response.
          format: double
        TotalCompaniesNowClassifiedForThisClassifier:
          type: integer
          description: Total companies classified for this model.
          format: int32
        TotalCompaniesForClassification:
          type: integer
          description: Companies considered for this response.
          format: int32
      additionalProperties: false
      description: Status and timing metrics for a classification operation.
    ModelWordScore:
      type: object
      properties:
        Word:
          type: string
          description: Word text from the model vocabulary.
          nullable: true
        Score:
          type: number
          description: Linear model weight for this word.
          format: double
          nullable: true
      additionalProperties: false
      description: Word and its weight from a trained classifier.
    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.).
    Results:
      required:
        - CompanyNumber
        - Name
      type: object
      properties:
        Name:
          type: string
          description: Company display name.
          nullable: true
        Score:
          type: number
          description: Classification score.
          format: double
        Confidence:
          type: number
          description: Confidence of the classification.
          format: double
        WordsMatched:
          type: integer
          description: Number of matched words.
          format: int32
        CompanyURL:
          type: string
          description: Company website URL.
          nullable: true
        WordScores:
          type: array
          items:
            $ref: '#/components/schemas/ModelWordScore'
          description: >-
            Per-term contributions to
            TDC_Global_Server_API_Core.Models.Classification.ClassificationResultBase.Score
            (featurized strength × model weight), plus a

            `(bias)` row when the model bias is non-zero. Values are

            rounded to four decimal places; their sum may differ slightly from
            TDC_Global_Server_API_Core.Models.Classification.ClassificationResultBase.Score
            (three decimals).
          nullable: true
        CompanyNumber:
          type: string
          description: Unique company number from the data source.
          nullable: true
        CompanyDetails:
          $ref: '#/components/schemas/ProcessedCompany'
      additionalProperties: false
      description: Represents the classification result for a single company.
    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 (defaults to "USA")
          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
        Employees:
          type: integer
          description: Exact number of employees
          format: int32
          nullable: true
        Turnover:
          type: integer
          description: Annual revenue/turnover value
          format: int64
          nullable: true
        NACEs:
          type: array
          items:
            type: string
          description: Primary industry classification rows associated with the company
          nullable: true
        RNACEs:
          type: array
          items:
            $ref: '#/components/schemas/RNace'
          description: Secondary industry classification rows associated with the company
          nullable: true
        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
    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
    RNace:
      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_IE.Models.RNace (secondary
        industry classification) rows.

        TDC_Global_Server_API_IE.Models.RNace.Code aligns with a primary NACEs
        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.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        An API key issued by The Data City, sent as: Authorization: Bearer
        YOUR_KEY

````