openapi: 3.2.0
info:
  title: Company Risk Scoring Company Details API
  version: 0.1.0
  description: "**Company Risk Scoring API v0.1.0**\n\nThis API provides a comprehensive service for evaluating the cybersecurity risk associated with external companies, primarily identified by their domain name. It's designed for B2B use cases like vendor risk management, cyber insurance underwriting, or competitive analysis.\n\n**Key Features:**\n\n* **Company Onboarding:** Add companies to the system for monitoring, either automatically by domain or manually with additional details.\n* **Security Scanning:** Initiate asynchronous scans against a company's domain to gather security data. Track scan job progress.\n* **Detailed Risk Categories:** Retrieve granular security assessment results for specific areas:\n    * Software Patching & Vulnerabilities\n    * Web Application Security\n    * Email Security (SPF, DMARC)\n    * System Reputation (IP blacklisting, abuse reports)\n    * SSL/TLS Configuration Strength\n    * System Hosting Environment (Cloud/CDN usage, ISP diversity)\n    * Data Breach History (Exposed credentials, breach dates)\n* **Overall Security Score:** Get a consolidated security score derived from individual category assessments.\n* **Company Firmographics:** Access essential company details like name, website, revenue, employee count, location, industry, and more.\n* **Flexible Data Retrieval:** Fetch results for individual risk categories or retrieve a combined report with all data points for a specific domain and scan job.\n* **Search & Listing:** List onboarded companies with pagination and search capabilities.\n\n**Authentication:**\n\nAccess requires either an API Key provided in the `X-API-Key` header or standard HTTP Basic Authentication."
tags:
- name: Company Details
paths:
  /api/b2b/crs/company-details/list:
    get:
      tags:
      - Company Details
      summary: List Company Details
      operationId: list_company_details_api_b2b_crs_company_details_list_get
      security:
      - APIKeyHeader: []
      - HTTPBasic: []
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyDetailsListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/b2b/crs/company-details/{domain}:
    get:
      tags:
      - Company Details
      summary: Domain Company Details
      operationId: domain_company_details_api_b2b_crs_company_details__domain__get
      security:
      - APIKeyHeader: []
      - HTTPBasic: []
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          title: Domain
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyDetails'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/b2b/crs/company-details/onboard/{domain}:
    post:
      tags:
      - Company Details
      summary: Onboard Company
      operationId: onboard_company_api_b2b_crs_company_details_onboard__domain__post
      security:
      - APIKeyHeader: []
      - HTTPBasic: []
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          title: Domain
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyOnboardingResponse'
        '404':
          description: Company details were not found and the company onboarding failed
        '409':
          description: Company already onboarded, request can't be repeated
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/b2b/crs/company-details/manual/onboard/:
    post:
      tags:
      - Company Details
      summary: Manual Onboard Company
      operationId: manual_onboard_company_api_b2b_crs_company_details_manual_onboard__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyOnboardingManualRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyOnboardingResponse'
        '404':
          description: Company details were not found and the company onboarding failed
        '409':
          description: Company already onboarded, request can't be repeated
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      - HTTPBasic: []
components:
  schemas:
    CompanyOnboardingResponse:
      properties:
        domain:
          type: string
          title: Domain
        company_details:
          anyOf:
          - $ref: '#/components/schemas/CompanyDetails'
          - type: 'null'
      type: object
      required:
      - domain
      title: CompanyOnboardingResponse
    CompanyOnboardingManualRequest:
      properties:
        domain:
          type: string
          title: Domain
        employee_count:
          type: integer
          title: Employee Count
      type: object
      required:
      - domain
      - employee_count
      title: CompanyOnboardingManualRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CEOData:
      properties:
        first_name:
          anyOf:
          - type: string
          - type: 'null'
          title: First Name
          description: First name of the CEO
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
          description: Last name of the CEO
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Title of the CEO
      type: object
      title: CEOData
    CompanyDetails:
      properties:
        name:
          type: string
          title: Name
          description: Full name of the company
          default: ''
        shorthand_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Shorthand Name
          description: Short or common name of the company
        website:
          type: string
          title: Website
          description: Official website of the company
          default: ''
        domain:
          type: string
          title: Domain
          description: Primary domain name of the company
          default: ''
        revenue:
          anyOf:
          - type: integer
          - type: 'null'
          title: Revenue
          description: Annual revenue of the company in USD
          default: 0
        revenue_range:
          anyOf:
          - type: string
          - type: 'null'
          title: Revenue Range
          description: Range of the company's annual revenue
        company_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Type
          description: Type of company (e.g., Private, Public)
        employee_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Employee Count
          description: Number of employees in the company
          default: 0
        employee_count_range:
          anyOf:
          - type: string
          - type: 'null'
          title: Employee Count Range
          description: Range of the number of employees
        year_founded:
          anyOf:
          - type: string
          - type: 'null'
          title: Year Founded
          description: Year the company was established
        location_data:
          anyOf:
          - $ref: '#/components/schemas/LocationData'
          - type: 'null'
          description: Detailed location information of the company
        contact_data:
          anyOf:
          - $ref: '#/components/schemas/ContactData'
          - type: 'null'
          description: Social media contact information
        ceo_data:
          anyOf:
          - $ref: '#/components/schemas/CEOData'
          - type: 'null'
          description: Information about the company's CEO
        competitor_list:
          items:
            type: object
          type: array
          title: Competitor List
          description: List of company's competitors
        funding_list:
          items:
            type: object
          type: array
          title: Funding List
          description: List of funding rounds or investments
        industry_list:
          items:
            type: string
          type: array
          title: Industry List
          description: List of industries the company operates in
        related_company_list:
          items:
            type: string
          type: array
          title: Related Company List
          description: List of related companies
        related_company_domain_list:
          items:
            type: string
          type: array
          title: Related Company Domain List
          description: List of domains of related companies
        total_funding:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Funding
          description: Total funding received by the company
        linkedin_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Linkedin Description
          description: Company description from LinkedIn
        owler_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Owler Description
          description: Company description from Owler
        g2_description:
          anyOf:
          - type: string
          - type: 'null'
          title: G2 Description
          description: Company description from G2
      type: object
      title: CompanyDetails
      examples:
      - ceo_data:
          first_name: Jane
          last_name: Doe
          title: CEO
        company_type: Private
        competitor_list:
        - name: Example Competitor A
          url: https://www.example.com/competitorA
        - name: Example Competitor B
          url: https://www.example.com/competitorB
        contact_data:
          facebook: https://www.facebook.com/ExampleCompany
          linkedin: https://www.linkedin.com/company/examplecompany/
        domain: examplecorp.com
        employee_count: 1500
        employee_count_range: 1,001-5,000 employees
        funding_list: []
        industry_list:
        - Technology Solutions
        - Cloud Services
        - Data Analytics
        linkedin_description: "About ExampleCorp\n\nExampleCorp is a leading provider of innovative technology solutions, helping businesses transform their operations. We deliver cutting-edge cloud services and data analytics to drive growth and efficiency. Our goal is to empower our clients with the tools they need to succeed in the digital age. \n\nWe are committed to excellence, collaboration, and sustainable practices. Join us in shaping the future of technology."
        location_data:
          city: Techville
          country_code: US
          country_name: United States
          full_address: 123 Innovation Drive, Techville, CA 90210
          state: California
          street: 123 Innovation Drive
          zipcode: '90210'
        name: ExampleCorp Inc.
        owler_description: ExampleCorp provides B2B technology solutions, focusing on cloud infrastructure and data management services for various industries.
        g2_description: ExampleCorp is highly rated on G2 for its customer support and ease of use in the cloud services category.
        related_company_domain_list: []
        related_company_list: []
        revenue: 500000000
        revenue_range: $500M - $1B (USD)
        shorthand_name: examplecorp
        website: https://www.examplecorp.com
        year_founded: '2010'
    CompanyDetailsListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/CompanyDetails'
          type: array
          title: Data
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - data
      - total
      - limit
      - offset
      title: CompanyDetailsListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LocationData:
      properties:
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          description: City where the company is located
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
          description: State or region where the company is located
        street:
          anyOf:
          - type: string
          - type: 'null'
          title: Street
          description: Street address of the company
        zipcode:
          anyOf:
          - type: string
          - type: 'null'
          title: Zipcode
          description: Postal code of the company's location
        country_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Code
          description: Two-letter country code
        country_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Name
          description: Full name of the country
        full_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Full Address
          description: Complete address of the company
      type: object
      title: LocationData
    ContactData:
      properties:
        facebook:
          anyOf:
          - type: string
          - type: 'null'
          title: Facebook
          description: Company's Facebook page URL
        linkedin:
          anyOf:
          - type: string
          - type: 'null'
          title: Linkedin
          description: Company's LinkedIn page URL
      type: object
      title: ContactData
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBasic:
      type: http
      scheme: basic