openapi: 3.2.0
info:
  title: FullEnrich API Documentation Company API
  version: 2.0.0
  description: 'FullEnrich API enables you to enrich B2B contacts with emails and phone numbers using data from 20+ providers.


    We are GDPR and CCPA compliant.'
servers:
- url: https://app.fullenrich.com/api/v2
tags:
- name: Company
paths:
  /company/search:
    post:
      summary: Search company
      description: Search for companies based on various filters. Multiple filters within the same field are combined with AND logic.
      operationId: postCompanySearch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCompanyRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SearchCompanyResponse'
                - $ref: '#/components/schemas/Metadata'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RateLimitExceeded:
                  value:
                    code: error.rate.limit
                    message: Too many requests. Try again in 1m
      security:
      - BearerAuth: []
      tags:
      - Company
  /company/lookup:
    post:
      summary: Look up company
      description: Look up a single company using its identifiers (domain, or professional network URL/ID). Returns the best matching company.
      operationId: postCompanyLookup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookUpCompanyRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LookUpCompanyResponse'
                - $ref: '#/components/schemas/LookUpMetadata'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RateLimitExceeded:
                  value:
                    code: error.rate.limit
                    message: Too many requests. Try again in 1m
      security:
      - BearerAuth: []
      tags:
      - Company
components:
  schemas:
    Company:
      type: object
      properties:
        id:
          type: string
          description: Unique company identifier
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: Company name
          example: Anthropic
        domain:
          type: string
          description: Company domain
          example: anthropic.com
        website:
          type: string
          description: Company website URL as declared by the company. May differ from `domain` (can include a subdomain, a path or tracking parameters). Omitted when not available.
          example: https://www.anthropic.com
        description:
          type: string
          description: Company description
          example: AI safety and research company building reliable, interpretable, and steerable AI systems.
        year_founded:
          type: integer
          description: Year the company was founded. Returns 0 when unknown.
          example: 2021
        headcount:
          type: integer
          description: Exact number of employees. May return 0 even when headcount_range is available.
          example: 2610
        headcount_range:
          type: string
          description: Employee count range (e.g., '1-10', '11-50', '51-200', '201-500', '501-1000', '1001-5000', '5001-10000', '10001+')
          example: 1001-5000
        company_type:
          type: string
          description: Type of company (e.g., 'Public Company', 'Privately Held', 'Nonprofit', 'Self-Employed', 'Partnership', 'Educational', 'Government Agency')
          example: Privately Held
        locations:
          type: object
          description: Company location information
          properties:
            headquarters:
              type: object
              description: Main headquarters address with structured location fields. Can be an empty object when no headquarters data is available.
              allOf:
              - $ref: '#/components/schemas/CompanyAddress'
            offices:
              type: array
              description: Additional office locations. Only contains raw address lines (line1, line2) without structured city/region/country fields. Can be null or an empty array.
              nullable: true
              items:
                $ref: '#/components/schemas/OfficeAddress'
        social_profiles:
          type: object
          description: Company's social media profiles
          allOf:
          - $ref: '#/components/schemas/CompanySocialProfile'
        specialties:
          type: array
          description: Specialties associated with the company
          items:
            type: string
          example:
          - artificial intelligence
          - machine learning
          - AI safety
        industry:
          type: object
          description: Company industry information
          properties:
            main_industry:
              type: string
              description: Primary industry category (e.g., 'Software Development', 'Computer Hardware Manufacturing', 'Financial Services', 'Healthcare', 'Retail')
              example: Software Development
        logo_url:
          type: string
          description: URL of the company logo hosted by FullEnrich, built from the company's professional network handle. Empty when the handle is unknown.
          example: https://app.fullenrich.com/logo/company/handle/anthropic
    CompanySocialProfile:
      type: object
      properties:
        professional_network:
          type: object
          description: Professional network profile information
          properties:
            id:
              type: integer
              description: Professional network profile ID
              example: 1234
            url:
              type: string
              description: Full professional network profile URL
              example: https://www.linkedin.com/company/anthropic
            handle:
              type: string
              description: Professional network profile handle/username
              example: anthropic
            connection_count:
              type: integer
              description: Number of professional network followers
              example: 125000
    OfficeAddress:
      type: object
      description: Office address. Unlike headquarters, office addresses only contain raw address lines without parsed location fields.
      properties:
        line1:
          type: string
          description: Street address
          example: 111 8th Ave
        line2:
          type: string
          description: Full location string (city, region, postal code, country code)
          example: New York, NY 10011, US
    CompanyAddress:
      type: object
      description: Structured headquarters address with parsed location fields
      properties:
        line1:
          type: string
          description: Address line 1 (street address)
          example: 548 Market St
        line2:
          type: string
          description: Address line 2 (full location string including city, region, postal code, and country code)
          example: San Francisco, CA 94105, US
        city:
          type: string
          description: City name
          example: San Francisco
        region:
          type: string
          description: State or region
          example: California
        country:
          type: string
          description: Country name
          example: United States
        country_code:
          type: string
          description: ISO country code
          example: US
    SearchCompanyRequest:
      type: object
      properties:
        offset:
          type: integer
          description: Number of companies to skip (use this for pagination). Maximum value is 10,000. To paginate beyond 10,000 results, use search_after instead.
          example: 20
        limit:
          type: integer
          description: 'Number of companies to return (default: 10, max: 100)'
          example: 20
        search_after:
          type: string
          description: Cursor-based pagination. Pass the search_after value from the previous response to get the next page. Works at any point in the result set, but is required to access results beyond the 10,000 offset limit. The search_after token does not have any expiration date. However, when the database is updated (every month), if the position of a company changes, the same search_after token might display different results.
          example: WzE1LjUzNDU2MywiYjQ5MDBiYmQtOTg5MS01Mzk1LWIyODUtOWEyOGNiZThjOTM3Il0=
        names:
          type: array
          description: Filter by company names. Use exact_match for precise company name matching.
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: Microsoft
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: true
          example:
          - value: Microsoft
            exact_match: true
            exclude: false
        domains:
          type: array
          description: Filter by company domains (e.g., 'google.com', 'microsoft.com'). Exact match recommended.
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: microsoft.com
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: true
          example:
          - value: microsoft.com
            exact_match: true
            exclude: false
        professional_network_ids:
          type: array
          description: Filter by professional network IDs.
          items:
            type: object
            properties:
              value:
                type: integer
                description: The integer value to filter by
                example: 1234
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the exact term must appear within the value, but can still be part of a longer string. When false (default), matching is flexible and tolerates slight variations such as missing or extra words. Matching is never case-sensitive.
                example: true
          example:
          - value: 1234
            exact_match: true
            exclude: false
        professional_network_urls:
          type: array
          description: Filter by professional network URLs.
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: https://www.linkedin.com/company/fullenrich
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: true
          example:
          - value: https://www.linkedin.com/company/fullenrich
            exact_match: true
            exclude: false
        keywords:
          type: array
          description: Filter by description of company
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: innovative and practical products
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: false
          example:
          - value: innovative and practical products
            exact_match: false
            exclude: false
        specialties:
          type: array
          description: Filter by specialties of company
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: AI safety
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: false
          example:
          - value: AI safety
            exact_match: false
            exclude: false
        industries:
          type: array
          description: Filter by company industries (e.g., 'Software Development', 'Computer Hardware Manufacturing', 'Housing and Community Development', 'Warehousing', 'Financial Services'). See [Industries](/api/v2/general/enums#company-industry) for the full list.
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: Software Development
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: false
          example:
          - value: Software Development
            exact_match: false
            exclude: false
          - value: Computer Hardware Manufacturing
            exact_match: false
            exclude: false
        types:
          type: array
          description: Filter by company types (e.g., 'Public Company', 'Privately Held', 'Nonprofit', 'Self-Employed', 'Partnership', 'Educational', 'Government Agency'). See [Company Types](/api/v2/general/enums#company-type) for the full list.
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: Public Company
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: true
          example:
          - value: Public Company
            exact_match: true
            exclude: false
        headquarters_locations:
          type: array
          description: Filter by headquarters locations (city names, regions, or countries)
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: San Francisco
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: false
          example:
          - value: San Francisco
            exact_match: false
            exclude: false
        founded_years:
          type: array
          description: Filter by founding years. Useful for targeting startups (recent years) or established companies.
          items:
            type: object
            properties:
              min:
                type: integer
                description: Minimum founding year (inclusive)
                example: 2010
              max:
                type: integer
                description: Maximum founding year (inclusive)
                example: 2024
              exclude:
                type: boolean
                description: If true, excludes companies founded in this range
                example: false
          example:
          - min: 2015
            max: 2024
            exclude: false
        headcounts:
          type: array
          description: 'Filter by company headcounts (number of employees). Use ranges to target specific company sizes (e.g., startups: 1-50, mid-size: 50-500, enterprise: 1000+).'
          items:
            type: object
            properties:
              min:
                type: integer
                description: Minimum number of employees (inclusive)
                example: 100
              max:
                type: integer
                description: Maximum number of employees (inclusive)
                example: 1000
              exclude:
                type: boolean
                description: If true, excludes companies in this range
                example: false
          example:
          - min: 100
            max: 500
            exclude: false
        company_ids:
          type: array
          description: Filter by specific company IDs
          items:
            type: object
            properties:
              value:
                type: string
                description: The string value to filter by
                example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              exclude:
                type: boolean
                description: If true, excludes results matching this value. If false or omitted (default), includes only matching results.
                example: false
              exact_match:
                type: boolean
                description: When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive.
                example: true
    LookUpCompanyResponse:
      type: object
      properties:
        companies:
          type: array
          description: Array containing the matching company. Returns an empty array if no match is found.
          items:
            $ref: '#/components/schemas/Company'
    LookUpMetadata:
      type: object
      properties:
        metadata:
          type: object
          properties:
            credits:
              type: number
              format: double
              description: Total number of credits consumed
              example: 0.25
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
      - code
      - message
    LookUpCompanyRequest:
      type: object
      description: Provide at least one identifier to match a single company. The domain or professional network URL/ID give the most reliable match.
      properties:
        domain:
          type: string
          description: Company domain to look up.
          example: anthropic.com
        professional_network_url:
          type: string
          description: Professional network URL of the company.
          example: https://www.linkedin.com/company/anthropic
        professional_network_id:
          type: integer
          description: Professional network ID of the company.
          example: 1883877
    Metadata:
      type: object
      properties:
        metadata:
          type: object
          properties:
            total:
              type: integer
              description: Total number of results matching the search criteria
              example: 20523
            credits:
              type: number
              format: double
              description: Total number of credits consumed
              example: 22.5
            offset:
              type: integer
              description: Number of results skipped (for pagination)
              example: 0
            search_after:
              type: string
              description: The cursor value returned by the previous page. Use this to paginate through the results.
              example: WzE1LjUzNDU2MywiYjQ5MDBiYmQtOTg5MS01Mzk1LWIyODUtOWEyOGNiZThjOTM3Il0=
    SearchCompanyResponse:
      type: object
      properties:
        companies:
          type: array
          description: Array of companies matching the search criteria. Returns empty array if no results found.
          items:
            $ref: '#/components/schemas/Company'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string