> ## 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 Bulk Enrichment (Beta)

> Company Bulk Enrichment API endpoint: match and enrich up to 50 companies in a single request, each item billed independently and returned in input order.

Enrich up to **50 companies in a single request**. Each item is matched and billed exactly like a standalone [`/company/enrich`](/docs/api-reference/company-enrichment) call. Bulk is a throughput tool, not a discount or a latency shortcut.

## How it works

* **Per item**: send the identifiers you already have for each company. Every item accepts the full set of `/company/enrich` identifiers and options (see [Company Enrichment](/docs/api-reference/company-enrichment) for the minimum-requirement rules).
* **Defaults vs. overrides**: top-level flags (`multiple_results` and `limit`, an enterprise feature switched on per account, `min_confidence`, `include_fields`, `exclude_fields`, ...) apply to every item. Set the same flag on an individual item to override the default for that item.
* **Order preserved**: `results` are returned in the same order as `items`. Each slot independently reports its `matches`, or an `error` if that item didn't match. A per-item failure never fails the whole batch.
* **Synchronous**: all results come back in one response. There is no job ID or polling.

## Billing

Each item is billed exactly like a standalone `/company/enrich` call, following your account's existing billing model. Bulk is a throughput convenience and doesn't change your pricing. An upfront check verifies the maximum possible cost of the batch before processing.

## Identifiers and metadata

Each item carries the same identifiers as single enrichment, plus an optional `metadata` object (up to 10 keys) that is echoed back unchanged on that item's result so you can map results to your own records. Values must be primitive: string, number, or boolean. Nested objects and arrays are rejected.

```json theme={null}
{
  "items": [
    { "domain": "acme.com", "metadata": { "crm_id": "abc-123" } },
    { "name": "Globex", "metadata": { "crm_id": "def-456" } }
  ]
}
```

## Limits and rate limits

| Limit | Value |
| - | - |
| Max items per request | **50** |
| Default rate limit | **10 requests/min** (each up to 50 records) |
| Max payload size | 1 MB |

<Note>
  The default rate limit is intended for evaluation. Higher limits can be provisioned per API key or account-wide. [Contact us](https://www.datalegion.ai/get-started) with your peak concurrent rate.
</Note>

## Batch size guidance

* **Real-time** (interactive SLA): keep batches small (10–20 items).
* **Asynchronous backfill**: use full 50-item batches and fan out multiple requests concurrently.


## OpenAPI

````yaml api-reference/bulk-spec.json POST /company/enrich/bulk
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/bulk:
    post:
      tags:
        - company
        - enrichment
      summary: Bulk enrich companies
      description: >-
        Enrich up to 50 companies in a single request. Each item is matched and
        billed independently, exactly like a standalone /company/enrich call.
        Top-level flags act as defaults; per-item flags override them. Results
        are returned in input order, and each item independently reports its
        matches or an error (a per-item failure does not fail the batch).
        Synchronous: all results are returned in one response (no polling).
        Default rate limit: 10 requests/min, each request up to 50 records.
      operationId: bulk_enrich_company_company_enrich_bulk_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCompanyEnrichRequest'
      responses:
        '200':
          description: >-
            Per-item results, in input order (each item is a match set or an
            error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCompanyEnrichResponse'
              example:
                results:
                  - matches:
                      - company:
                          legion_id: c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c
                          company_name: acme corp
                          company_domain: acme.com
                        match_metadata:
                          matched_on:
                            - domain
                          match_type: exact
                          match_confidence: high
                    total: 1
                    metadata:
                      crm_id: abc-123
                  - error: No company found matching the provided parameters.
                    metadata:
                      crm_id: def-456
        '400':
          description: >-
            Bad request - malformed batch (e.g. empty items or more than 50
            items)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Insufficient credits for the maximum possible cost of the batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - API key not permitted for this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large - request body exceeds the 1 MB 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 (default 10 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;
            retry after the seconds in the Retry-After header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BulkCompanyEnrichRequest:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 50
          title: Items
          description: List of company enrichment requests (1-50 items).
          items:
            $ref: '#/components/schemas/BulkCompanyItem'
        multiple_results:
          type: boolean
          title: Multiple Results
          description: >-
            Default for all items: if true, return multiple matches sorted by
            confidence. Enterprise only: enabled per account (ask your account
            manager or support@datalegion.ai); without it the request answers
            403 feature_not_available. Each match returned is billed.
          default: false
        limit:
          type: integer
          maximum: 10
          minimum: 1
          title: Limit
          description: >-
            Default for all items: maximum number of results per item when
            multiple_results=true (default: 2, max: 10).
          default: 2
        min_confidence:
          anyOf:
            - type: string
            - type: 'null'
          title: Min Confidence
          description: >-
            Default for all items: minimum match confidence level to include
            ('high', 'moderate', or 'low').
        titlecase:
          type: boolean
          title: Titlecase
          description: 'Default for all items: if true, format text fields in title case.'
          default: false
        required_fields:
          anyOf:
            - type: string
            - type: 'null'
          title: Required Fields
          description: >-
            Default for all items: comma-separated list of fields that must be
            present, else the match is filtered out.
        include_fields:
          anyOf:
            - type: string
            - type: 'null'
          title: Include Fields
          description: >-
            Default for all items: comma-separated list of fields to include in
            the response. If omitted, all fields are returned.
        exclude_fields:
          anyOf:
            - type: string
            - type: 'null'
          title: Exclude Fields
          description: >-
            Default for all items: comma-separated list of fields to exclude
            from the response. Applied after include_fields.
        pretty_print:
          type: boolean
          title: Pretty Print
          description: If true, pretty-print the JSON response with indentation.
          default: false
      title: BulkCompanyEnrichRequest
      description: >-
        Bulk company enrichment request. Top-level flags act as defaults applied
        to every item; per-item flags override them.
      example:
        items:
          - domain: acme.com
            metadata:
              crm_id: abc-123
          - company_name: Globex
            metadata:
              crm_id: def-456
    BulkCompanyEnrichResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          title: Results
          description: Per-item results, in the same order as the input items.
          items:
            $ref: '#/components/schemas/BulkCompanyItemResult'
      title: BulkCompanyEnrichResponse
      description: Bulk company enrichment response.
    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.
    BulkCompanyItem:
      allOf:
        - $ref: '#/components/schemas/CompanyEnrichmentRequest'
        - type: object
          properties:
            metadata:
              anyOf:
                - additionalProperties: true
                  type: object
                - type: 'null'
              title: Metadata
              description: >-
                Optional key-value object (max 10 keys) echoed back unchanged on
                this item's result, for correlating results to your records.
                Values must be primitive (string, number, or boolean); nested
                objects and arrays are rejected.
      title: BulkCompanyItem
      description: >-
        A single company enrichment request within a bulk call. Accepts every
        /company/enrich identifier and option, plus optional metadata. Per-item
        flags override the top-level defaults.
    BulkCompanyItemResult:
      type: object
      properties:
        matches:
          type: array
          title: Matches
          description: >-
            Matches for this item (present on success), capped at the item's
            limit.
          items:
            $ref: '#/components/schemas/CompanyMatchResponse'
        total:
          type: integer
          title: Total
          description: Number of matches found for this item.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: >-
            Error message when this item could not be matched (e.g. no match or
            invalid input). Per-item failures are isolated; other items still
            succeed.
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: The metadata you supplied for this item, echoed back unchanged.
      title: BulkCompanyItemResult
      description: >-
        Result for one item in a bulk company request. Each slot independently
        reports matches or an error, with your metadata echoed back.
    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. Enterprise
            only: enabled per account (ask your account manager or
            support@datalegion.ai); without it the request answers 403
            feature_not_available. Each match returned is billed.
          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
    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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.