components:
  responses: {}
  schemas:
    CompaniesEnrichRequest:
      description: >-
        Request to enrich company data with firmographics, spend, and
        technographics
      example:
        companies:
          ids:
            - '78040737422146204640576'
            - 1698C53EBC888758570396E0334965C1
        fields:
          - firmographics
          - spend
          - technographics
        filters:
          technographics:
            categories:
              ids:
                - 319D067B229178F03BCFA
            products:
              ids:
                - 814
            vendors:
              ids:
                - 316
        pagination:
          technographics:
            limit: 25
            offset: 0
      properties:
        companies:
          $ref: '#/components/schemas/CompaniesFilter'
        fields:
          description: Which data categories to include in the response
          items:
            $ref: '#/components/schemas/FieldGroups'
          type: array
        filters:
          $ref: '#/components/schemas/EnrichFilters'
        pagination:
          $ref: '#/components/schemas/RequestPagination'
      required:
        - companies
      title: CompaniesEnrichRequest
      type: object
    CompaniesEnrichResponse:
      description: Response containing enriched company data
      properties:
        companies:
          items:
            $ref: '#/components/schemas/CompanyEnrichObject'
          type: array
      title: CompaniesEnrichResponse
      type: object
    CompaniesFilter:
      description: Filter companies by IDs
      example:
        ids:
          - '78040737422146204640576327630924184547'
          - 1698C53EBC888758570396E0334965C1
      properties:
        ids:
          description: Array of hex-encoded company IDs
          items:
            $ref: '#/components/schemas/HexId'
          maxItems: 50
          minItems: 1
          type: array
      required:
        - ids
      title: CompaniesFilter
      type: object
    CompanyEnrichObject:
      description: Enriched company data
      example:
        company_id: '78040737422146204640576327630924184547'
        firmographics:
          company_name: Example Corp
          country_code: US
          domain_name: example.com
          hg_id: '78040737422146204640576327630924184547'
        spend:
          all:
            - absolute_spend: 125000
              category_id: 319D067B229178F03BCFA1DA4AC4DEDE
              category_name: Software
              country_code: US
          all_count: 1
        technographics:
          installs:
            - country_code: US
              product_id: 814
              product_intensity: 5
              product_last_verified_date: '2024-05-20'
              product_name: Java
              vendor_name: Oracle
          installs_count: 1
      properties:
        company_id:
          $ref: '#/components/schemas/HexId'
        firmographics:
          $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics
        spend:
          description: Spend data
          properties:
            all:
              description: Array of spend records
              items:
                $ref: >-
                  #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Spend
              type: array
            all_count:
              description: Total count of spend records
              type: integer
          type: object
        technographics:
          description: Technographics data
          properties:
            installs:
              description: Array of technology installs
              items:
                $ref: >-
                  #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.Install
              type: array
            installs_count:
              description: Total count of installs
              type: integer
          type: object
      title: CompanyEnrichObject
      type: object
    EnrichFilters:
      description: Filters for enrich request
      properties:
        technographics:
          $ref: '#/components/schemas/TechnographicsFilters'
      title: EnrichFilters
      type: object
    FieldGroups:
      description: Data categories to include in the response
      enum:
        - firmographics
        - spend
        - technographics
      title: FieldGroups
      type: string
    HexId:
      description: Unique hexadecimal identifier
      example: 1698C53EBC888758570396E0334965C1
      maxLength: 32
      title: HexId
      type: string
    IdFilter:
      description: Filter by hex-encoded IDs (assumes ANY_PRESENT inclusion method)
      properties:
        ids:
          description: Array of hex-encoded IDs
          items:
            $ref: '#/components/schemas/HexId'
          type: array
      title: IdFilter
      type: object
    JsonErrorResponse:
      properties:
        errors:
          items:
            properties:
              detail:
                example: null value where string expected
                type: string
              source:
                properties:
                  pointer:
                    example: /data/attributes/petName
                    type: string
                required:
                  - pointer
                type: object
              title:
                example: Invalid value
                type: string
            required:
              - title
              - source
              - detail
            type: object
          type: array
      required:
        - errors
      title: JsonErrorResponse
      type: object
    Limit:
      default: 10
      description: The number of records to return in the request.
      maximum: 50
      title: Limit
      type: integer
    NumericIdFilter:
      description: Filter by numeric IDs (assumes ANY_PRESENT inclusion method)
      properties:
        ids:
          description: Array of numeric IDs
          items:
            type: integer
          type: array
      title: NumericIdFilter
      type: object
    Offset:
      default: 0
      description: Used for paginating records.
      minimum: 0
      title: Offset
      type: integer
    Pagination:
      description: Common pagination parameters
      properties:
        limit:
          $ref: '#/components/schemas/Limit'
        offset:
          $ref: '#/components/schemas/Offset'
      title: Pagination
      type: object
    RequestPagination:
      description: Pagination parameters for companies and nested data
      properties:
        spend:
          $ref: '#/components/schemas/Pagination'
        technographics:
          $ref: '#/components/schemas/Pagination'
      title: RequestPagination
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics:
      description: Firmographic data for a company
      oneOf:
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Basic
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Full
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics
    TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Basic:
      description: Firmographic basic data for a company
      properties:
        company_id:
          type: string
        country_code:
          type: string
        country_name:
          type: string
        industry:
          type: string
        industry_id:
          type: integer
        name:
          type: string
        url:
          type: string
        url_normalized:
          type: string
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Basic
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Full:
      allOf:
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Basic
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Premium
      description: Full firmographic data for a company
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Full
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Premium:
      description: Firmographic premium data for a company
      properties:
        city_name:
          type: string
        global_hq_postal_code:
          type: string
        global_hq_naics_code:
          type: string
        global_hq_company_id:
          type: string
        sic_names:
          items:
            type: string
          type: array
        continent_name:
          type: string
        global_hq_name:
          type: string
        global_hq_sic_names:
          items:
            type: string
          type: array
        it_spend:
          type: number
        global_hq_fortune_500_ranking:
          type: integer
        global_hq_region:
          type: string
        global_hq_subcontinent_name:
          type: string
        global_hq_industry_id:
          type: integer
        employees_total:
          type: integer
        postal_code:
          type: string
        global_hq_naics_name:
          type: string
        global_hq_state_name:
          type: string
        sic_codes:
          items:
            type: string
          type: array
        fortune_500_ranking:
          type: integer
        global_hq_url:
          type: string
        employees_range:
          type: string
        revenue_range:
          type: string
        global_hq_industry:
          type: string
        global_hq_revenue_range:
          type: string
        global_hq_url_normalized:
          type: string
        global_hq_continent_name:
          type: string
        region:
          type: string
        company_level:
          type: string
        state_name:
          type: string
        subcontinent_name:
          type: string
        global_hq_employees_range:
          type: string
        global_hq_city_name:
          type: string
        global_hq_forbes_2000_ranking:
          type: integer
        global_hq_country_name:
          type: string
        revenue_total:
          type: number
        naics_code:
          type: string
        global_hq_country_code:
          type: string
        global_hq_sic_codes:
          items:
            type: string
          type: array
        forbes_2000_ranking:
          type: integer
        naics_name:
          type: string
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Firmographics.Premium
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Spend:
      description: Spend data for a company
      oneOf:
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Basic
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Full
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Spend
    TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Basic:
      description: Spend basic data for a company
      properties:
        absolute_spend:
          description: Total spend in USD
          type: number
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Basic
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Full:
      allOf:
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Basic
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Premium
      description: Full spend data for a company
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Full
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Premium:
      description: Spend premium data for a company
      properties:
        category_description:
          type: string
        category_id:
          type: string
        category_name:
          type: string
        country_code:
          type: string
        country_name:
          type: string
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Spend.Premium
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.Install:
      description: Technology install/usage data
      oneOf:
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallBasic
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallFull
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.Install
    TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallBasic:
      description: Technology install/usage basic data
      properties:
        country_code:
          type: string
        intensity:
          type: integer
        last_verified_at:
          format: date-time
          type: string
        product_id:
          type: integer
        product_name:
          type: string
        vendor_name:
          type: string
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallBasic
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallFull:
      allOf:
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallBasic
        - $ref: >-
            #/components/schemas/TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallPremium
      description: Full technology install/usage data
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallFull
      type: object
    TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallPremium:
      description: Technology install/usage premium data
      properties:
        attribute_name_array:
          items:
            type: string
          type: array
        category_leaf_code:
          type: string
        category_leaf_id:
          type: string
        category_level1_name:
          type: string
        category_level2_name:
          type: string
        category_level3_name:
          type: string
        category_level4_name:
          type: string
        category_level5_name:
          type: string
        company_group_id:
          type: string
        first_verified_at:
          format: date-time
          type: string
        location_count:
          type: integer
        product_description:
          type: string
        total_count:
          type: integer
        vendor_id:
          type: integer
        vendor_url:
          type: string
      title: TalariaWeb.Schemas.V2.Companies.Enrich.Technographics.InstallPremium
      type: object
    TechnographicsFilters:
      description: Filters for technographics data
      example:
        product_categories:
          ids:
            - 319D067B229178F03BCFA1DA4AC4DEDE
        products:
          ids:
            - 814
        vendors:
          ids:
            - 316
      properties:
        product_categories:
          $ref: '#/components/schemas/IdFilter'
        products:
          $ref: '#/components/schemas/NumericIdFilter'
        vendors:
          $ref: '#/components/schemas/NumericIdFilter'
      title: TechnographicsFilters
      type: object
    UnauthorizedResponse:
      properties:
        errors:
          items:
            properties:
              detail:
                example: The token provided is not valid
                type: string
              source:
                type: 'null'
              title:
                example: Unauthorized
                type: string
            required:
              - title
              - detail
            type: object
          type: array
      title: UnauthorizedResponse
      type: object
  securitySchemes:
    authorization:
      in: header
      name: Authorization
      type: apiKey
info:
  description: >
    # HG Insights API v2


    The v2 API provides company enrichment with firmographics, spend, and
    technographics data.


    ## Authentication


    All API requests require authentication using an API token.


    ### Getting Your Token


    Contact your HG Insights account manager to obtain an API token.


    ### Using Your Token


    Include your token in the `Authorization` header:


    ```bash

    curl -X POST "https://api.hginsights.com/data-api/api/v2/companies/enrich" \
      -H "Authorization: YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"companies": {"ids": ["COMPANY_ID"]}}'
    ```


    **Important:** Do not include "Bearer" prefix. Use the token directly.


    ### Token Format


    v2 tokens start with `hg_v2_` followed by a random string.


    Example: `hg_v2_K3WnkKrSyVD8yOoGTu1oqujB0f37eJuen1wvV2Ptg0`


    ---


    ## Company Enrichment


    The enrichment endpoint returns firmographics, spend, and technographics
    data for companies.


    ### Request Example


    ```json

    {
      "companies": {
        "ids": ["1698C53EBC888758570396E0334965C1"]
      },
      "fields": ["firmographics", "spend", "technographics"]
    }

    ```


    ### Parameters


    | Parameter | Type | Required | Description |

    |-----------|------|----------|-------------|

    | `companies.ids` | array | Yes | Company IDs (hex format, max 50) |

    | `fields` | array | No | Data categories to return |


    ### Field Groups


    - **firmographics** - Company info, location, revenue, employees

    - **spend** - IT spend by category

    - **technographics** - Technology installs


    ### Response Example


    ```json

    {
      "companies": [
        {
          "company_id": "1698C53EBC888758570396E0334965C1",
          "firmographics": {
            "name": "Walmart Inc.",
            "url": "walmart.com",
            "country_code": "US",
            "employees_total": 2100000,
            "revenue_total": 680985000000
          },
          "spend": {
            "all": [...],
            "all_count": 135
          },
          "technographics": {
            "installs": [...],
            "installs_count": 5900
          }
        }
      ]
    }

    ```


    ### Filtering Technographics


    Filter installs by vendor, product, or category:


    ```json

    {
      "companies": {"ids": ["..."]},
      "fields": ["technographics"],
      "filters": {
        "technographics": {
          "vendors": {"ids": [316]},
          "products": {"ids": [814]}
        }
      }
    }

    ```


    ---


    ## Entitlements


    Your API token includes entitlements that determine which data you can
    access.


    ### Basic Tier


    **Firmographics:** Company name, URL, country, industry


    **Spend:** Absolute spend amounts only


    **Technographics:** Not included


    ### Full Tier


    **Firmographics:** All 48 fields including revenue, employees, HQ info,
    rankings


    **Spend:** Full details with category name, description, country


    **Technographics:** Full install data with product, vendor, intensity,
    dates, categories


    ### Checking Your Entitlements


    Make a request and check which fields are returned. Fields outside your
    entitlements will be omitted from the response.


    ### Upgrading


    Contact your HG Insights account manager to upgrade your entitlements.
  license:
    name: HG Insights terms of service
    url: https://hginsights.com/contact-hg/terms-of-service
  title: HG Insights API
  version: ''
openapi: 3.0.0
paths:
  /data-api/v2/companies/enrich:
    post:
      callbacks: {}
      description: >
        Unified endpoint to enrich company data with firmographics, spend, and
        technographics.


        Select which data categories to include using the `fields` parameter. By
        default, all categories are included.

        Filter technographics by categories, vendors, or products using the
        `filters` parameter.

        Control pagination for both companies and nested technographics data.
      operationId: enrich_companies
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompaniesEnrichRequest'
        description: Enrich Request
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompaniesEnrichResponse'
          description: Enrich Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
      summary: Enrich Companies
      tags:
        - Companies
security:
  - authorization: []
servers:
  - url: https://api.hginsights.com
tags: []
