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

# Company Enrichment

> Company Enrichment API endpoint: match companies by domain, name, LinkedIn ID, social URL, or ticker and append 50+ firmographic and workforce data points.

## Minimum Requirements

Every request must include **at least one** identifier. Requests with no identifiers return `400 Bad Request`.

### Identifiers

| Field           | Description                               | Example                                |
| --------------- | ----------------------------------------- | -------------------------------------- |
| `legion_id`     | Company Legion ID (exact match)           | `c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c` |
| `domain`        | Company website domain                    | `google.com`                           |
| `name`          | Company name (fuzzy matching)             | `Google`                               |
| `linkedin_id`   | LinkedIn company numeric ID               | `1441`                                 |
| `social_url`    | LinkedIn company page or other social URL | `https://linkedin.com/company/google`  |
| `ticker_symbol` | Stock ticker symbol                       | `GOOGL`                                |

### Qualifiers

These fields refine matching but are not sufficient on their own:

| Field      | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `industry` | Narrows name-based matching (e.g., `"software development"`) |


## OpenAPI

````yaml POST /company/enrich
openapi: 3.1.0
info:
  title: Data Legion API
  description: API for enriching, searching, and discovering person and company data
  version: 1.0.0
servers:
  - url: https://api.datalegion.ai
security:
  - APIKeyHeader: []
paths:
  /company/enrich:
    post:
      tags:
        - company
        - enrichment
      summary: Enrich company by multiple parameters
      description: >-
        Find the best matching company/companies based on provided parameters.
        Supports 6 matching methods: domain, company name (fuzzy with optional
        industry), LinkedIn ID, social URL, ticker symbol, and Legion ID. Inputs
        are automatically cleaned and normalized.
      operationId: enrich_company_company_enrich_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyEnrichmentRequest'
      responses:
        '200':
          description: Success - company/companies found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyMatchesResponse'
              example:
                matches:
                  - company:
                      legion_id: c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c
                      name:
                        cleaned: stripe inc
                        display: Stripe
                        raw:
                          - Stripe, Inc.
                          - Stripe
                      headline:
                        cleaned: financial infrastructure for the internet
                        raw:
                          - Financial infrastructure for the internet
                      description:
                        cleaned: >-
                          stripe is a financial infrastructure platform for
                          businesses...
                        raw:
                          - >-
                            Stripe is a financial infrastructure platform for
                            businesses...
                      domain: stripe.com
                      linkedin_url: https://www.linkedin.com/company/stripe
                      linkedin_id: '2135371'
                      linkedin_followers: 1250000
                      linkedin_employee_count: 8000
                      industry: financial services
                      type: private
                      size: 5001-10000
                      founded: 2010
                      legion_employee_count: 8500
                      legion_average_tenure: 28.4
                      legion_new_hire_count:
                        1m: 85
                        3m: 240
                        6m: 420
                        12m: 780
                      legion_attrition_count:
                        1m: 35
                        3m: 95
                        6m: 170
                        12m: 310
                      legion_employee_growth_rate:
                        1m: 0.012
                        3m: 0.035
                        6m: 0.068
                        12m: 0.125
                      legion_turnover_rate:
                        1m: 0.004
                        3m: 0.011
                        6m: 0.02
                        12m: 0.036
                      legion_seniority_distribution:
                        c_level: 15
                        vp: 85
                        director: 320
                        manager: 1100
                        senior: 2800
                        junior: 3200
                      legion_job_function_distribution:
                        engineering: 3400
                        sales: 1200
                        operations: 800
                        marketing: 600
                        information_technology: 500
                        product: 450
                      legion_expense_category_distribution:
                        research_and_development: 3850
                        general_and_administrative: 2850
                        sales_and_marketing: 1800
                      legion_tenure_distribution:
                        <1yr: 1200
                        1-2yr: 2100
                        2-5yr: 3200
                        5-10yr: 1400
                        10+yr: 600
                      legion_education_distribution:
                        bachelors: 4200
                        masters: 2800
                        high_school: 950
                        associates: 400
                        doctorate: 150
                      legion_seniority_growth_rate:
                        senior:
                          1m: 0.015
                          3m: 0.04
                          6m: 0.08
                          12m: 0.15
                      legion_job_function_growth_rate:
                        engineering:
                          1m: 0.018
                          3m: 0.05
                          6m: 0.09
                          12m: 0.17
                      legion_expense_category_growth_rate:
                        research_and_development:
                          1m: 0.016
                          3m: 0.045
                          6m: 0.085
                          12m: 0.16
                      tickers: []
                      socials:
                        - network: x
                          url: https://www.x.com/stripe
                          username: stripe
                          id: '16177321'
                        - network: github
                          url: https://github.com/stripe
                          username: stripe
                          id: null
                      domains:
                        - domain: stripe.com
                        - domain: stripe.dev
                      legion_employee_count_by_month:
                        - month: 2026-01
                          count: 8500
                          net_change: 50
                          growth_rate: 0.006
                          hires: 120
                          departures: 70
                        - month: 2025-12
                          count: 8450
                          net_change: 65
                          growth_rate: 0.008
                          hires: 135
                          departures: 70
                      num_sources: 5
                      last_seen: 2026-01
                      build_version: 1.3.2_2026-07-12
                    match_metadata:
                      matched_on:
                        - domain
                      match_type: exact
                      match_confidence: high
                total: 1
        '400':
          description: Bad request - invalid input or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required - insufficient credits or expired contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - API key not authorized for this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - no company matches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large - request body exceeds size limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error - invalid field format or value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - rate limit exceeded (100 requests per minute)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable - database or service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CompanyEnrichmentRequest:
      properties:
        legion_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Legion Id
          description: Company Legion ID (exact match)
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Company website domain (e.g., google.com)
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Company name (fuzzy matching)
        linkedin_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Id
          description: LinkedIn company numeric ID
        social_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Social Url
          description: >-
            Social profile URL (LinkedIn, Facebook, Crunchbase, X/Twitter,
            GitHub - will be normalized and detected)
        ticker_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Ticker Symbol
          description: Stock ticker symbol (e.g., GOOGL)
        industry:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry
          description: Industry filter (used with name matching for better accuracy)
        multiple_results:
          type: boolean
          title: Multiple Results
          description: If true, return multiple matches sorted by confidence
          default: false
        limit:
          type: integer
          maximum: 10
          minimum: 1
          title: Limit
          description: 'Maximum results when multiple_results=true (default: 2, max: 10)'
          default: 2
        min_confidence:
          anyOf:
            - type: string
            - type: 'null'
          title: Min Confidence
          description: 'Minimum match confidence: ''high'', ''moderate'', or ''low'''
        titlecase:
          type: boolean
          title: Titlecase
          description: >-
            If true, format text fields in title case (names, company names,
            locations). Raw fields, IDs, URLs, codes, and confidence fields are
            excluded.
          default: false
        required_fields:
          anyOf:
            - type: string
            - type: 'null'
          title: Required Fields
          description: >-
            Comma-separated list of fields that must be present, else the match
            is filtered out. Supports top-level fields ('domain,socials'), a
            non-empty list subfield ('socials.network'), or a subfield equal to
            a value ('type:public', 'socials.network:linkedin'). Unknown field
            names or out-of-range enum values return HTTP 400.
        include_fields:
          anyOf:
            - type: string
            - type: 'null'
          title: Include Fields
          description: >-
            Comma-separated list of fields to include in response. If omitted,
            all fields are returned.
        exclude_fields:
          anyOf:
            - type: string
            - type: 'null'
          title: Exclude Fields
          description: >-
            Comma-separated list of fields to exclude from response. Applied
            after include_fields filter.
        pretty_print:
          type: boolean
          title: Pretty Print
          description: If true, pretty-print JSON response with indentation.
          default: false
      type: object
      title: CompanyEnrichmentRequest
      description: Request model for company enrichment.
      example:
        domain: stripe.com
    CompanyMatchesResponse:
      properties:
        matches:
          items:
            $ref: '#/components/schemas/CompanyMatchResponse'
          type: array
          title: Matches
          description: >-
            List of matches sorted by confidence (descending). Capped at the
            request's `limit`.
        total:
          type: integer
          title: Total
          description: >-
            For /company/search and /company/discover, the total number of rows
            matching the query's WHERE clause across the database (not just this
            page). For /company/enrich, the number of matches found for the
            input identifier. On search/discover, if the exact count exceeds its
            time budget (broad, low-selectivity queries) it falls back to the
            query planner's row estimate, and if that is unavailable, to the
            size of the returned page; the response header `Total-Count-Status`
            reports which (`exact`, `estimate`, or `page`).
      type: object
      required:
        - matches
        - total
      title: CompanyMatchesResponse
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Error type/code
        message:
          type: string
          title: Message
          description: Human-readable error message
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - items: {}
              type: array
            - type: 'null'
          title: Details
          description: Additional error details (for validation errors)
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Error response model for customer-facing API.
    CompanyMatchResponse:
      properties:
        company:
          $ref: '#/components/schemas/CompanyResponse'
        match_metadata:
          anyOf:
            - $ref: '#/components/schemas/MatchMetadata'
            - type: 'null'
      type: object
      required:
        - company
      title: CompanyMatchResponse
    CompanyResponse:
      properties:
        legion_id:
          type: string
          title: Legion Id
        name:
          anyOf:
            - $ref: '#/components/schemas/CompanyNameResponse'
            - type: 'null'
        headline:
          anyOf:
            - $ref: '#/components/schemas/CleanedRawResponse'
            - type: 'null'
        description:
          anyOf:
            - $ref: '#/components/schemas/CleanedRawResponse'
            - type: 'null'
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
        linkedin_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Id
        linkedin_followers:
          anyOf:
            - type: integer
            - type: 'null'
          title: Linkedin Followers
        linkedin_employee_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Linkedin Employee Count
        industry:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        size:
          anyOf:
            - type: string
            - type: 'null'
          title: Size
        founded:
          anyOf:
            - type: integer
            - type: 'null'
          title: Founded
        legion_employee_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Legion Employee Count
        legion_average_tenure:
          anyOf:
            - type: number
            - type: 'null'
          title: Legion Average Tenure
        legion_new_hire_count:
          anyOf:
            - $ref: '#/components/schemas/TimeBucketIntResponse'
            - type: 'null'
        legion_attrition_count:
          anyOf:
            - $ref: '#/components/schemas/TimeBucketIntResponse'
            - type: 'null'
        legion_turnover_rate:
          anyOf:
            - $ref: '#/components/schemas/TimeBucketFloatResponse'
            - type: 'null'
        legion_employee_growth_rate:
          anyOf:
            - $ref: '#/components/schemas/TimeBucketFloatResponse'
            - type: 'null'
        legion_seniority_distribution:
          anyOf:
            - type: object
              additionalProperties:
                type: integer
            - type: 'null'
          title: Seniority Distribution
          description: >-
            Employee count by seniority level (c_level, owner, partner, vp,
            director, manager, senior, junior, training, intern)
        legion_job_function_distribution:
          anyOf:
            - type: object
              additionalProperties:
                type: integer
            - type: 'null'
          title: Job Function Distribution
          description: Employee count by job function (engineering, sales, marketing, etc.)
        legion_expense_category_distribution:
          anyOf:
            - type: object
              additionalProperties:
                type: integer
            - type: 'null'
          title: Expense Category Distribution
          description: >-
            Employee count by P&L expense category (general_and_administrative,
            research_and_development, sales_and_marketing, cost_of_services,
            not_applicable)
        legion_tenure_distribution:
          anyOf:
            - type: object
              additionalProperties:
                type: integer
            - type: 'null'
          title: Tenure Distribution
          description: Employee count by tenure bucket (<1yr, 1-2yr, 2-5yr, 5-10yr, 10+yr)
        legion_education_distribution:
          anyOf:
            - type: object
              additionalProperties:
                type: integer
            - type: 'null'
          title: Education Distribution
          description: >-
            Employee count by education level (doctorate, masters, bachelors,
            associates, high_school)
        legion_seniority_growth_rate:
          anyOf:
            - type: object
              additionalProperties:
                $ref: '#/components/schemas/TimeBucketFloatResponse'
            - type: 'null'
          title: Seniority Growth Rate
          description: Growth rate per seniority level with time buckets (1m, 3m, 6m, 12m)
        legion_job_function_growth_rate:
          anyOf:
            - type: object
              additionalProperties:
                $ref: '#/components/schemas/TimeBucketFloatResponse'
            - type: 'null'
          title: Job Function Growth Rate
          description: Growth rate per job function with time buckets (1m, 3m, 6m, 12m)
        legion_expense_category_growth_rate:
          anyOf:
            - type: object
              additionalProperties:
                $ref: '#/components/schemas/TimeBucketFloatResponse'
            - type: 'null'
          title: Expense Category Growth Rate
          description: Growth rate per expense category with time buckets (1m, 3m, 6m, 12m)
        tickers:
          items:
            $ref: '#/components/schemas/CompanyTickerResponse'
          type: array
          title: Tickers
          default: []
        socials:
          items:
            $ref: '#/components/schemas/CompanySocialResponse'
          type: array
          title: Socials
          default: []
        domains:
          items:
            $ref: '#/components/schemas/CompanyDomainResponse'
          type: array
          title: Domains
          default: []
        legion_employee_count_by_month:
          items:
            $ref: '#/components/schemas/EmployeeCountByMonthResponse'
          type: array
          title: Legion Employee Count By Month
          default: []
        num_sources:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Sources
        last_seen:
          anyOf:
            - type: string
              description: YYYY-MM format
            - type: 'null'
          title: Last Seen
        build_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Build Version
      type: object
      required:
        - legion_id
      title: CompanyResponse
      description: Complete company enrichment response.
    MatchMetadata:
      properties:
        matched_on:
          items:
            type: string
          type: array
          title: Matched On
          description: Fields that matched between request and person
        match_type:
          type: string
          title: Match Type
          description: 'Type of match: exact, fuzzy, or partial'
        match_confidence:
          type: string
          title: Match Confidence
          description: 'Match confidence level: high, moderate, or low'
      type: object
      required:
        - match_type
        - match_confidence
      title: MatchMetadata
      description: Metadata about the match.
    CompanyNameResponse:
      properties:
        cleaned:
          anyOf:
            - type: string
            - type: 'null'
          title: Cleaned
        display:
          anyOf:
            - type: string
            - type: 'null'
          title: Display
          description: Best-quality name with original casing preserved (premium tier)
        raw:
          items:
            type: string
          type: array
          title: Raw
          default: []
      type: object
      title: CompanyNameResponse
      description: Company name structure with cleaned, display, and raw[] variants.
    CleanedRawResponse:
      properties:
        cleaned:
          anyOf:
            - type: string
            - type: 'null'
          title: Cleaned
        raw:
          items:
            type: string
          type: array
          title: Raw
          default: []
      type: object
      title: CleanedRawResponse
      description: >-
        Generic {cleaned, raw[]} structure used for titles, degrees, headlines,
        summaries, skills, languages, and certification names/institutions.
    TimeBucketIntResponse:
      properties:
        1m:
          anyOf:
            - type: integer
            - type: 'null'
          title: 1m
          description: Value over the last month
        3m:
          anyOf:
            - type: integer
            - type: 'null'
          title: 3m
          description: Value over the last 3 months
        6m:
          anyOf:
            - type: integer
            - type: 'null'
          title: 6m
          description: Value over the last 6 months
        12m:
          anyOf:
            - type: integer
            - type: 'null'
          title: 12m
          description: Value over the last 12 months
      type: object
      title: TimeBucketIntResponse
      description: Time-bucketed integer values (1m, 3m, 6m, 12m).
    TimeBucketFloatResponse:
      properties:
        1m:
          anyOf:
            - type: number
            - type: 'null'
          title: 1m
          description: Rate over the last month
        3m:
          anyOf:
            - type: number
            - type: 'null'
          title: 3m
          description: Rate over the last 3 months
        6m:
          anyOf:
            - type: number
            - type: 'null'
          title: 6m
          description: Rate over the last 6 months
        12m:
          anyOf:
            - type: number
            - type: 'null'
          title: 12m
          description: Rate over the last 12 months
      type: object
      title: TimeBucketFloatResponse
      description: Time-bucketed float values (1m, 3m, 6m, 12m).
    CompanyTickerResponse:
      properties:
        symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Symbol
        exchange:
          anyOf:
            - type: string
            - type: 'null'
          title: Exchange
      type: object
      title: CompanyTickerResponse
    CompanySocialResponse:
      properties:
        network:
          anyOf:
            - type: string
            - type: 'null'
          title: Network
          description: Social network name (e.g., x, github, facebook)
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: Profile URL
        username:
          anyOf:
            - type: string
            - type: 'null'
          title: Username
          description: Username or handle
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: Account ID
      type: object
      title: CompanySocialResponse
      description: Company social media profile.
    CompanyDomainResponse:
      properties:
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Associated company domain
      type: object
      title: CompanyDomainResponse
      description: Company alternative domain.
    EmployeeCountByMonthResponse:
      properties:
        month:
          anyOf:
            - type: string
            - type: 'null'
          title: Month
          description: YYYY-MM format
        count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Count
        net_change:
          anyOf:
            - type: integer
            - type: 'null'
          title: Net Change
        growth_rate:
          anyOf:
            - type: number
            - type: 'null'
          title: Growth Rate
        hires:
          anyOf:
            - type: integer
            - type: 'null'
          title: Hires
        departures:
          anyOf:
            - type: integer
            - type: 'null'
          title: Departures
      type: object
      title: EmployeeCountByMonthResponse
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: API-Key

````