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

# Enrich a company by properties

> **Cost:** 1 credit when a company is returned or when the properties cannot resolve a company domain. Paid expansions are charged only when returned.

Each requested expansion (`financial`, `keywords`, `naicsCodes`, `technologies`, or `workforce`) adds 1 credit per returned company. `workforce` includes the latest 12 months of history. Use its `nextCursor` with `GET /v2/companies/workforce` to retrieve each preceding 12-month page for another 1 credit. Repeating an expansion does not multiply its cost.

Resolves and enriches a company using one or more identifying properties. When several properties are provided, all of them must match. If several companies match, the highest-ranked company is used.



## OpenAPI

````yaml openapi/v2.json POST /v2/companies/enrich
openapi: 3.0.4
info:
  title: Company Enrich API v2
  description: >-
    The Company Enrich API v2 provides programmatic access to company and person
    data for enrichment, search, and lead generation.


    ## Key Features


    - **Company Enrichment** — Enrich company profiles by domain or identifying
    properties, and retrieve stored companies by ID.

    - **Company Search** — Search and filter companies with cursor pagination,
    counts, and previews.

    - **Semantic and Lookalike Search** — Find companies using natural-language
    queries or similar company domains.

    - **People Enrichment** — Retrieve people by ID, identify people from their
    email address, and find work email addresses.

    - **People Search** — Search people by position, seniority, department,
    location, education, and company with cursor pagination, counts, and
    previews.

    - **Reference Data** — Look up industries, geographic data, keywords,
    technologies, and job titles.


    V2 intentionally excludes saved company lists, list-based exports, and
    filtering searches by saved-list IDs. These features remain available in V1
    and are not planned for V2.


    ## Authentication


    All API requests require a Bearer token passed in the `Authorization`
    header:


    ```

    Authorization: Bearer YOUR_API_TOKEN

    ```


    You can generate API tokens from your
    [dashboard](https://companyenrich.com/dashboard).


    ## Credits


    Most API calls consume credits. The credit cost for each endpoint is
    documented in its description. You can check your remaining credit balance
    using the User endpoint.


    ## Rate Limiting


    The global API limiter allows **500 requests per minute** per IP address.
    Authenticated API routes also use a per-user route limiter based on plan
    capabilities.

    Supplementary lookup endpoints (such as keyword/technology/industry
    autocompletes) use a separate per-user route-level bucket.
  termsOfService: https://companyenrich.com/terms-and-conditions
  contact:
    url: https://companyenrich.com/
    email: support@companyenrich.com
  version: 2.0.0
servers:
  - url: https://api.companyenrich.com
security:
  - Bearer: []
tags:
  - name: Company / Enrichment
    description: >-
      Enrich company data by domain, properties, or in batch. Get company
      details by ID.
  - name: Company / Bulk Enrichment
    description: >-
      Create and manage asynchronous bulk enrichment jobs for large domain
      lists.
  - name: Company / Search
    description: Search companies by filters with pagination and cursor scrolling.
  - name: People / Search
    description: >-
      Search people by various criteria with page-based or cursor-based
      pagination.
  - name: People / Enrichment
    description: >-
      Resolve work email addresses for individual people in realtime or
      background jobs.
  - name: Geo
    description: >-
      Endpoints for looking up geographic data including regions, countries,
      states, and cities.
  - name: Industries
    description: >-
      Endpoints for listing available industry classifications used in company
      search filters.
  - name: Keywords
    description: Endpoints for looking up keywords used in company search filters.
  - name: Technologies
    description: Endpoints for looking up technologies used in company search filters.
  - name: User
    description: >-
      Endpoints for retrieving information about the authenticated user,
      including credit balance and account details.
  - name: Positions
    description: Endpoints for looking up job positions and titles.
paths:
  /v2/companies/enrich:
    post:
      tags:
        - Company / Enrichment
      summary: Enrich a company by properties
      description: >-
        **Cost:** 1 credit when a company is returned or when the properties
        cannot resolve a company domain. Paid expansions are charged only when
        returned.


        Each requested expansion (`financial`, `keywords`, `naicsCodes`,
        `technologies`, or `workforce`) adds 1 credit per returned company.
        `workforce` includes the latest 12 months of history. Use its
        `nextCursor` with `GET /v2/companies/workforce` to retrieve each
        preceding 12-month page for another 1 credit. Repeating an expansion
        does not multiply its cost.


        Resolves and enriches a company using one or more identifying
        properties. When several properties are provided, all of them must
        match. If several companies match, the highest-ranked company is used.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyEnrichV2Request'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '402':
          description: Payment Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/HttpValidationProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    CompanyEnrichV2Request:
      type: object
      properties:
        name:
          maxLength: 250
          type: string
          description: The company name
          nullable: true
        linkedinUrl:
          maxLength: 2048
          type: string
          description: The company LinkedIn URL
          format: uri
          nullable: true
        linkedinId:
          maxLength: 100
          type: string
          description: The company LinkedIn ID
          nullable: true
        twitterUrl:
          maxLength: 2048
          type: string
          description: The company Twitter/X URL
          format: uri
          nullable: true
        facebookUrl:
          maxLength: 2048
          type: string
          description: The company Facebook URL
          format: uri
          nullable: true
        instagramUrl:
          maxLength: 2048
          type: string
          description: The company Instagram URL
          format: uri
          nullable: true
        youtubeUrl:
          maxLength: 2048
          type: string
          description: The company YouTube URL
          format: uri
          nullable: true
        expand:
          type: array
          items:
            enum:
              - financial
              - keywords
              - naicsCodes
              - technologies
              - workforce
            type: string
          description: >-
            Additional company data to include. Each requested expansion is
            charged per returned company, on top of the base cost:


            - `financial`: 1 credit

            - `keywords`: 1 credit

            - `naicsCodes`: 1 credit

            - `technologies`: 1 credit

            - `workforce`: 1 credit. Includes the latest 12 months of history;
            each earlier 12-month page from `GET /v2/companies/workforce` costs
            another 1 credit.
          nullable: true
    CompanyResponse:
      required:
        - id
        - domain
        - website
        - logoUrl
        - updatedAt
      type: object
      properties:
        id:
          type: string
          description: The CompanyEnrich ID of the company
          format: uuid
        name:
          type: string
          description: The company name
          nullable: true
        legalName:
          type: string
          description: The legal name of the company
          nullable: true
        domain:
          type: string
          description: The primary domain of the company
        website:
          type: string
          description: The company website URL
        logoUrl:
          type: string
          description: The company logo URL
        description:
          type: string
          description: The company description
          nullable: true
        type:
          $ref: '#/components/schemas/NullableOfCompanyType'
        foundedYear:
          type: integer
          description: The year the company was founded
          format: int32
          nullable: true
        employees:
          $ref: '#/components/schemas/NullableOfCompanyEmployees'
        revenue:
          $ref: '#/components/schemas/NullableOfCompanyRevenue'
        industry:
          type: string
          description: The primary industry of the company
          nullable: true
        industries:
          type: array
          items:
            type: string
          description: The industries associated with the company
          nullable: true
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CompanyCategory'
          description: >-
            The categories associated with the company, from most to least
            specific
          nullable: true
        location:
          $ref: '#/components/schemas/CompanyLocationResponse'
        socials:
          $ref: '#/components/schemas/CompanySocialsResponse'
        updatedAt:
          type: string
          description: When the company data was last updated
          format: date-time
        financial:
          $ref: '#/components/schemas/CompanyFinancialResponse'
        keywords:
          type: array
          items:
            type: string
          description: >-
            Keywords associated with the company. Included when `keywords` is
            requested in `expand`.
          nullable: true
        naicsCodes:
          type: array
          items:
            type: string
          description: >-
            The NAICS codes associated with the company. Included when
            `naicsCodes` is requested in `expand`.
          nullable: true
        technologies:
          type: array
          items:
            type: string
          description: >-
            Technologies used by the company. Included when `technologies` is
            requested in `expand`.
          nullable: true
        workforce:
          $ref: '#/components/schemas/CompanyWorkforceResponse'
    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
    HttpValidationProblemDetails:
      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
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    NullableOfCompanyType:
      enum:
        - private
        - public
        - self-employed
        - self-owned
        - partnership
        - nonprofit
        - educational
        - government
        - null
      description: The company type
      nullable: true
    NullableOfCompanyEmployees:
      enum:
        - 1-10
        - 11-50
        - 51-200
        - 201-500
        - 501-1K
        - 1K-5K
        - 5K-10K
        - over-10K
        - null
      description: The estimated employee count range
      nullable: true
    NullableOfCompanyRevenue:
      enum:
        - under-1m
        - 1m-10m
        - 10m-50m
        - 50m-100m
        - 100m-200m
        - 200m-1b
        - over-1b
        - null
      description: The estimated annual revenue range in USD
      nullable: true
    CompanyCategory:
      enum:
        - b2b
        - b2c
        - b2g
        - e-commerce
        - media
        - service-provider
        - mobile
        - saas
        - local-business
    CompanyLocationResponse:
      type: object
      properties:
        country:
          $ref: '#/components/schemas/CompanyCountryResponse'
        state:
          $ref: '#/components/schemas/CompanyStateResponse'
        city:
          $ref: '#/components/schemas/CompanyCityResponse'
        address:
          type: string
          description: The company street address
          nullable: true
        postalCode:
          type: string
          description: The company postal code
          nullable: true
        phone:
          type: string
          description: The company phone number
          nullable: true
      description: The company location and contact details
      nullable: true
    CompanySocialsResponse:
      type: object
      properties:
        linkedinUrl:
          type: string
          description: The company LinkedIn URL
          nullable: true
        linkedinId:
          type: string
          description: The company LinkedIn ID
          nullable: true
        twitterUrl:
          type: string
          description: The company Twitter/X URL
          nullable: true
        facebookUrl:
          type: string
          description: The company Facebook URL
          nullable: true
        instagramUrl:
          type: string
          description: The company Instagram URL
          nullable: true
        angellistUrl:
          type: string
          description: The company AngelList URL
          nullable: true
        crunchbaseUrl:
          type: string
          description: The company Crunchbase URL
          nullable: true
        youtubeUrl:
          type: string
          description: The company YouTube URL
          nullable: true
        githubUrl:
          type: string
          description: The company GitHub URL
          nullable: true
        g2Url:
          type: string
          description: The company G2 URL
          nullable: true
      description: The company social profiles
      nullable: true
    CompanyFinancialResponse:
      type: object
      properties:
        stockSymbol:
          type: string
          description: The company stock symbol
          nullable: true
        stockExchange:
          type: string
          description: The stock exchange where the company is listed
          nullable: true
        totalFunding:
          type: integer
          description: The total disclosed funding in USD
          format: int64
          nullable: true
        fundingStage:
          type: string
          description: The latest funding stage
          nullable: true
        fundingDate:
          type: string
          description: The date of the latest funding round
          format: date-time
          nullable: true
        fundingRounds:
          type: array
          items:
            $ref: '#/components/schemas/CompanyFundingRoundResponse'
          description: The company's disclosed funding rounds
          nullable: true
      description: >-
        Financial and funding data. Included when `financial` is requested in
        `expand`.
      nullable: true
    CompanyWorkforceResponse:
      required:
        - companyId
        - domain
        - observedEmployeeCount
        - departmentHeadcount
        - unclassifiedHeadcount
        - historyFrom
        - historyTo
      type: object
      properties:
        companyId:
          type: string
          description: The CompanyEnrich ID of the company
          format: uuid
        domain:
          type: string
          description: The canonical company domain
        observedEmployeeCount:
          type: integer
          description: >-
            The observed number of distinct current employees in the people
            dataset
          format: int32
        employeeCountRange:
          $ref: '#/components/schemas/NullableOfCompanyEmployees'
        departmentHeadcount:
          $ref: '#/components/schemas/CompanyWorkforceDepartmentResponse'
        unclassifiedHeadcount:
          type: integer
          description: Observed headcount that could not be classified by department
          format: int32
        historyFrom:
          type: string
          description: The inclusive first month of the returned 12-month history window
          format: date
        historyTo:
          type: string
          description: The exclusive end of the returned 12-month history window
          format: date
        history:
          type: array
          items:
            $ref: '#/components/schemas/CompanyWorkforceHistoryResponse'
          description: >-
            Workforce change points within the history window, newest first. A
            point at the start carries forward the last known earlier headcount
            when available.
          nullable: true
        nextCursor:
          type: string
          description: >-
            Pass this cursor with the company ID or domain to GET
            /v2/companies/workforce to fetch the preceding year for 1 credit.
            Omitted when no older history is available. Expires 30 minutes after
            the first page.
          nullable: true
      description: Workforce insights. Included when `workforce` is requested in `expand`.
      nullable: true
    CompanyCountryResponse:
      required:
        - code
        - name
      type: object
      properties:
        code:
          type: string
          description: The ISO 3166-1 alpha-2 country code
        name:
          type: string
          description: The country name
      description: The country where the company is located
      nullable: true
    CompanyStateResponse:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: integer
          description: The CompanyEnrich state ID
          format: int32
        name:
          type: string
          description: The state or province name
        code:
          type: string
          description: The ISO 3166-2 subdivision code
          nullable: true
      description: The state or province where the company is located
      nullable: true
    CompanyCityResponse:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: integer
          description: The CompanyEnrich city ID
          format: int32
        name:
          type: string
          description: The city name
      description: The city where the company is located
      nullable: true
    CompanyFundingRoundResponse:
      type: object
      properties:
        date:
          type: string
          description: The funding round date
          format: date-time
          nullable: true
        amount:
          type: string
          description: The disclosed funding amount and currency
          nullable: true
        type:
          type: string
          description: The funding round type
          nullable: true
        url:
          type: string
          description: A source URL for the funding round
          nullable: true
        investors:
          type: string
          description: The disclosed investors
          nullable: true
    CompanyWorkforceDepartmentResponse:
      type: object
      properties:
        cSuite:
          type: integer
          description: Observed c-suite headcount
          format: int32
          nullable: true
        productManagement:
          type: integer
          description: Observed product management headcount
          format: int32
          nullable: true
        engineeringTechnical:
          type: integer
          description: Observed engineering and technical headcount
          format: int32
          nullable: true
        design:
          type: integer
          description: Observed design headcount
          format: int32
          nullable: true
        education:
          type: integer
          description: Observed education headcount
          format: int32
          nullable: true
        finance:
          type: integer
          description: Observed finance headcount
          format: int32
          nullable: true
        humanResources:
          type: integer
          description: Observed human resources headcount
          format: int32
          nullable: true
        informationTechnology:
          type: integer
          description: Observed information technology headcount
          format: int32
          nullable: true
        legal:
          type: integer
          description: Observed legal headcount
          format: int32
          nullable: true
        marketing:
          type: integer
          description: Observed marketing headcount
          format: int32
          nullable: true
        medicalHealth:
          type: integer
          description: Observed medical and health headcount
          format: int32
          nullable: true
        operations:
          type: integer
          description: Observed operations headcount
          format: int32
          nullable: true
        sales:
          type: integer
          description: Observed sales headcount
          format: int32
          nullable: true
        consulting:
          type: integer
          description: Observed consulting headcount
          format: int32
          nullable: true
      description: Observed headcount grouped by department
    CompanyWorkforceHistoryResponse:
      required:
        - date
        - observedEmployeeCount
        - departmentHeadcount
        - unclassifiedHeadcount
      type: object
      properties:
        date:
          type: string
          description: The first day of the snapshot month
          format: date
        observedEmployeeCount:
          type: integer
          description: The observed number of distinct employees in the people dataset
          format: int32
        employeeCountRange:
          $ref: '#/components/schemas/NullableOfCompanyEmployees'
        departmentHeadcount:
          $ref: '#/components/schemas/CompanyWorkforceDepartmentResponse'
        unclassifiedHeadcount:
          type: integer
          description: Observed headcount that could not be classified by department
          format: int32
  securitySchemes:
    Bearer:
      type: apiKey
      description: >-
        API Token used for authentication. Example: "Authorization: Bearer
        {token}"
      name: Authorization
      in: header
      x-bearer-format: bearer

````

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