TrueBiz Web Presence Review API

openapi: 3.2.0
info:
  title: TrueBiz Async Web Presence Review API
  version: 1.0.0
  description: '# Introduction

    TrueBiz provides tools to automate assessing a merchant''s web presence through the entire customer lifecycle.


    # Authentication


    All requests to TrueBiz require an API key to be sent as a header.  The expected header name is "X-API-KEY".

    '
servers:
- url: https://ae.truebiz.io
  description: Production
tags:
- name: Web Presence Review
  description: "\nWeb Presence Review endpoints allow you to provide information about a business for TrueBiz to review.\n We look at the content on the website, find social media profiles, review sites, and other\nbroader web presence. For security reasons, any domain provided will be reduced to the registered domain known\nto Mozilla's Public Suffix List (e.g. https://www.bbc.co.uk/some/page -> bbc.co.uk). These endpoints will then\nreview the web presence starting with the index page for that domain (e.g. bbc.co.uk -> https://bbc.co.uk/).\n"
paths:
  /api/v1/company/search:
    post:
      operationId: core_api_company_review_company
      summary: Review Company
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequest'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      description: "Conduct a web presence review of a business. You must identify the business one of two ways:\n\n- **By domain** — submit `domain` (accepts a bare domain, full URL, or email; we extract the registered\n   domain).\n- **By name + address** — submit `submitted_business_name` together with at least one address field\n   (`address_line_1`, `city`, `state_province`, `postal_code`, or `country`).\n\nAll other fields (`submitted_phone`, `submitted_email`, `submitted_full_name`, `submitted_description`)\nare optional and help us identify the business and surface additional detail.\n\nRequires a valid `X-API-KEY` header. Rate limited to 5 requests per second.\n\n**Testing:** You can use `example.org` as a test domain to verify your integration without\nhitting real data sources or incurring any cost to you. It returns a static fixture response with realistic data."
      tags:
      - Web Presence Review
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyQuery'
        required: true
      security:
      - AsyncApiKeyAuth: []
      - AsyncPropelAuthBearer: []
components:
  schemas:
    FollowRatio:
      title: FollowRatio
      description: An enumeration.
      enum:
      - Low
      - Medium
      - High
      type: string
    AverageEngagement:
      title: AverageEngagement
      description: An enumeration.
      enum:
      - Low
      - Medium
      - High
      type: string
    ConnectionSourceType:
      title: ConnectionSourceType
      description: An enumeration.
      enum:
      - Referring site
      - Duplicate website text
      - External email domain
      - Shared executive
      - Shared phone number
      - Shared credentials
      - Cohosted domain
      - Redirect domain
      - Searched domain redirects
      - Associated person
      - Phone owner
      - Shared address
      - Shared email
      - Associated web page
      type: string
    PolicySource:
      title: PolicySource
      type: object
      properties:
        type:
          title: Source type
          description: The type of source.
          example: Privacy Policy
          type: string
        url:
          title: Source URL
          description: The URL of the source.
          example: https://www.example.com/privacy
          minLength: 1
          maxLength: 2083
          format: uri
          type: string
        title:
          title: Source title
          description: The title of the source.
          example: Acme Inc. Privacy Policy
          type: string
        company_name:
          title: Company name
          description: The name of the company as it appears in the source.
          example: Acme Inc.
          type: string
        language:
          title: Source language
          description: The language of the source.
          example: en
          type: string
        last_updated:
          title: Last updated
          description: The date the source was last updated.
          example: '2021-01-01'
          type: string
        change_policy:
          title: Change policy
          description: The policy for changes to the source.
          example: Example Co reserves the right to make changes to this Privacy Policy. Any updates will be posted on our website.
          type: string
        policy_contact:
          title: Contact
          description: The contact information for the source.
          example: support@example.com
          type: string
        synopsis:
          title: Synopsis
          description: A brief synopsis of the source.
          example: This privacy policy outlines the types of personal information that is received and collected and how it is used. It also outlines the steps we take to protect your personal information.
          type: string
        has_placeholder_text:
          title: Has placeholder text?
          description: Indicates whether the source contains placeholder text.
          example: false
          type: boolean
      required:
      - type
      - url
    CompanyMatchBlockedDomain:
      title: CompanyMatchBlockedDomain
      type: object
      properties:
        created_at:
          title: Blocked since
          description: When the block was created
          example: '2023-12-25T19:30:25.000+00:00'
          type:
          - string
          - 'null'
          format: date-time
        expires_at:
          title: Blocked until
          description: When the block expires
          example: '2030-12-29T23:59:59.000+00:00'
          type:
          - string
          - 'null'
          format: date-time
        explanation:
          title: Block explanation
          description: Human-readable explanation for why the domain was blocked
          type:
          - string
          - 'null'
    CustomerReviews:
      title: CustomerReviews
      type: object
      properties:
        analysis:
          title: Analysis
          description: An analysis of the review data gathered from providers
          allOf:
          - $ref: '#/components/schemas/core__api__schemas__customer_review__Analysis'
        providers:
          title: Providers
          description: A list of review data from different providers
          default: []
          type: array
          items:
            $ref: '#/components/schemas/CustomerReviewsData'
    LevelOfConcern:
      title: LevelOfConcern
      description: An enumeration.
      enum:
      - low
      - medium
      - high
      - critical
      type: string
    ConcernFlag:
      title: ConcernFlag
      description: An enumeration.
      enum:
      - customer_service_concerns
      - product_quality_concerns
      - product_authenticity_concerns
      - delivery_concerns
      - return_or_refund_concerns
      - fraud_concerns
      type: string
    Coordinates:
      title: Coordinates
      type: object
      properties:
        lat:
          title: Lat
          type: number
        lon:
          title: Lon
          type: number
      required:
      - lat
      - lon
    ConnectionSource:
      title: ConnectionSource
      type: object
      properties:
        type:
          title: Name
          description: Name of the connected entity.
          example: Acme Consulting Inc.
          allOf:
          - $ref: '#/components/schemas/ConnectionSourceType'
        context:
          title: Context
          description: Data on the connection.
          example: example.com is also located at 123 Main Street, Chicago, IL
          type: string
        url:
          title: URL
          description: The URL of the source.
          example: https://example.com
          minLength: 1
          maxLength: 65536
          format: uri
          type: string
    RiskAnalysis:
      title: RiskAnalysis
      type: object
      properties:
        fraud_risk:
          $ref: '#/components/schemas/FraudRisk'
    Risk:
      title: Risk
      type: object
      properties:
        category:
          title: Category
          description: The general area this risk classification belongs to.
          default: ''
          example: website
          minLength: 1
          maxLength: 64
          type: string
        subcategory:
          title: Subcategory
          description: The subdivision of the category.
          default: ''
          example: security
          minLength: 1
          maxLength: 64
          type: string
        name:
          title: Name
          description: The machine-readable name of the risk element being considered.
          default: ''
          example: ssl_configuration
          minLength: 1
          maxLength: 255
          type: string
        display_name:
          title: Display name
          description: The human-readable name of the risk element being considered.
          default: ''
          example: Webserver SSL configuration
          minLength: 1
          maxLength: 255
          type: string
        score:
          title: Score
          description: The percentage score of how risky we consider the data for this item to be, denoted as a flat integer that should be divided by 100 (e.g. 1000 -> 10%). Higher numbers are more risky.
          default: ''
          example: 0
          minimum: 0
          maximum: 10000
          type: integer
        description:
          title: Description
          description: A plaintext explanation of the risk.
          default: ''
          example: The website's SSL configuration is not valid, indicating site security is not well maintained.
          minLength: 1
          maxLength: 512
          type: string
        classification_type:
          title: Classification type
          description: The classification type indicating whether the data point(s) find that this is an indicatorof validity, risk, or something your team should take notice of.
          default: Validity
          example: Validity
          allOf:
          - $ref: '#/components/schemas/RiskType'
    ConnectedEntity:
      title: ConnectedEntity
      type: object
      properties:
        name:
          title: Name
          description: Name of the connected entity.
          example: Acme Consulting Inc.
          type: string
        domain:
          title: URL
          description: domain of the connected entity.
          example: example.com
          type: string
        sources:
          title: Source
          description: The data source that establishes the connection.
          default: []
          example: Duplicate website text
          type: array
          items:
            $ref: '#/components/schemas/ConnectionSource'
        content_flags:
          title: Content flags
          description: A list of potentially concerning flags in the web content.
          example:
          - Animal Cruelty
          type: array
          items:
            type: string
        multi_level_marketing_name:
          title: Multi level marketing name
          description: The name of a known multi-level-marketing brand found in the web content.
          example: Amway
          type: string
        primary_language:
          title: Primary language
          description: Evaluation of the primary language used for web content.
          example: English
          type: string
        is_webserver_responsive:
          title: Webserver responsive
          description: Indicates whether the entity's webserver is responsive.
          example: true
          type: boolean
    DetectedBrand:
      title: DetectedBrand
      type: object
      properties:
        name:
          title: Brand Name
          description: The name of the brand.
          example: Nike
          type: string
        count:
          title: Frequency
          description: The number of times the brand name was detected in the company's principal page(s)
          example: 10
          type: integer
        action:
          title: Action
          description: The action that should be taken for the brand.
          example: warn
          type: string
      required:
      - name
      - count
      - action
    Domain:
      title: Domain
      description: 'this has come to be a collection of technical data points, rather than anything intuitively related to the "Domain"

        err on having things that could be in website_content being more intelligable to non-technical users

        and technical stuff directly in domain'
      type: object
      properties:
        name:
          title: Domain name
          description: The fully qualified domain name.
          example: acme.com
          minLength: 1
          maxLength: 2048
          type:
          - string
          - 'null'
        registration_date:
          title: Registration date
          description: The date the domain was initially registered on.
          example: '1992-07-14'
          type:
          - string
          - 'null'
          format: date
        last_update_date:
          title: Last update date
          description: The date the domain's registration info was last updated on.
          example: '2021-12-15'
          type:
          - string
          - 'null'
          format: date
        expiration_date:
          title: Expiration date
          description: The date on which the domain's registration info is due to expire. If the expiration date has passed, this adds risk as the domain can be reassigned to a new company.
          example: '2028-07-12'
          type:
          - string
          - 'null'
          format: date
        is_resolvable:
          title: Is resolvable?
          description: A domain that responded with a valid A, AAAA, or CNAME record at the time of lookup. Unresolvable domains are frequently caused by typos on input.
          example: true
          type: boolean
        is_registered:
          title: Is registered?
          description: A domain that was present in the ICANN registry at the time of lookup. Unregistered domains can be purchased at any time, and thus are risky. This is frequently caused by typos on input.
          example: true
          type: boolean
        is_parked:
          title: Is parked?
          description: A domain that is registered, but not connected to a legitimate site. It is instead pointed at a parking page, typically owned by the registrar.
          example: false
          type: boolean
        is_known_free_email_host:
          title: Is known free email host?
          description: A domain known for providing free email signups.  Typically, a corporate representative of google (or another hosted domain provider) will use their corporate email address, not their public email service domain.
          example: false
          type: boolean
        is_known_social_media_domain:
          title: Is known social media domain?
          description: A domain that is registered to a known social media entity.
          example: false
          type: boolean
        is_known_marketplace_domain:
          title: Is known marketplace domain?
          description: A domain that is registered to a known marketplace entity (e.g. alibaba, amazon, fiverr).
          example: false
          type: boolean
        is_known_top_domain:
          title: Is known top domain?
          description: A domain that is known to be one of the most popular sites on the internet.
          example: false
          type: boolean
        is_known_hosting_provider_domain:
          title: Is known hosting provider domain?
          description: A domain that is known to be registered to a known hosting provider (e.g. company.hostingprovider.com and not company.com).
          example: false
          type: boolean
        is_non_business:
          title: Is non business?
          description: A domain with a top level domain that indicates it is unlikely to be a business (e.g. .edu, .gov).
          example: false
          type: boolean
        is_ssl_valid:
          title: Is SSL valid?
          description: A domain for which SSL was properly configured at the time of the check.
          example: true
          type: boolean
        is_webserver_responsive:
          title: Is webserver responsive?
          description: A domain for which the responding web server(s) responds to a simple HTTP or HTTPS request on port 80 or 443.
          example: true
          type: boolean
        screenshot:
          title: Screenshot
          description: Links to download a screenshot of the domain in multiple sizes.
          allOf:
          - $ref: '#/components/schemas/Screenshot'
        historical_archives:
          title: Historical archives
          description: Archives of the website from past dates.
          type: array
          items:
            $ref: '#/components/schemas/HistoricalArchive'
        registrar:
          title: Registrar
          description: Information about the domain's registrar
          allOf:
          - $ref: '#/components/schemas/Registrar'
        hosting_providers:
          title: Hosting providers
          description: Information about the host(s) of the webserver(s) used by the company's website
          example:
          - name: Google
            country: United States
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/HostingProvider'
        has_robots_txt:
          title: Has a valid robots.txt?
          description: A website sophistication signal that indicates content scraping permissibility.
          default: true
          example: true
          type:
          - boolean
          - 'null'
        has_apex_and_www:
          title: Has apex and www?
          description: Indicates both the apex domain (e.g. example.com) and www subdomain (e.g. www.example.com) work or correctly forward traffic.
          default: true
          example: true
          type:
          - boolean
          - 'null'
        estimated_tech_spend:
          title: Estimated tech spend
          description: An estimage of the monthly spend on website technologies derived from the visible premium libraries and tools.
          example: 1000
          type:
          - integer
          - 'null'
        estimated_tech_spend_history:
          title: Estimated tech spend history
          description: Estimates of the monthly spend based on the website technologies used as times in the past.
          example:
          - spend: 850
            detected_date: '2022-06-01'
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TechSpendRecord'
        website_tech_activity:
          title: Website tech activity
          description: The number of total, added, and removed website technologies by month.
          example:
          - year: 2023
            month: 6
            added: 4
            removed: 1
            total: 25
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TechActivityMonth'
        domains_with_matching_credentials:
          title: Domains with matching credentials
          description: Domains that share technology credentials with the website.
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CredentialMatchDomain'
        inbound_linking_domains_count:
          title: Inbound linking domains count
          description: The number of unique domains that have links to the website (aka backlinks).
          example: 5
          type:
          - integer
          - 'null'
        inbound_redirects:
          title: Redirects
          description: A list of domains that redirect to the website.
          example:
          - example.xyz
          type:
          - array
          - 'null'
          items:
            type: string
        cohosted_domains:
          title: Co-hosted domains
          description: A list of domains that are hosted on the same IP address as the website, and likely are owned or managed by the same entity.
          example:
          - example.xyz
          type:
          - array
          - 'null'
          items:
            type: string
    PostalServiceFlag:
      title: PostalServiceFlag
      description: '"residential" indicates that the address is a residential address.

        "po_box" indicates that the address is a Postoffice Box rather than a physical address.

        "virtual_address" indicates that the address is a private business receiving mail for clients.

        "vacant" indicates that the USPS has marked the address as being vacant.

        "inactive" indicates that the USPS does not deliver to this address.

        "unreliable" indicates that that there was not enough address information to validate a specific address.

        "unconfirmed" indicates that the USPS does not maintain Delivery Point Validation data for this address.'
      enum:
      - residential
      - po_box
      - virtual_address
      - vacant
      - inactive
      - general_delivery
      - unreliable
      - unconfirmed
      type: string
    EmploymentRecord:
      title: EmploymentRecord
      type: object
      properties:
        company_name:
          title: Company name
          description: The company name.
          example: ACME LLC.
          type: string
        title:
          title: Job title
          description: The job title.
          example: Co-founder & CEO
          type: string
        start_date:
          title: Start date
          description: The date the person started at the job.
          example: '2018-09-01'
          type: string
          format: date
      required:
      - company_name
    ProjectionDay:
      title: ProjectionDay
      type: object
      properties:
        name:
          title: Name
          description: Day of the week
          type: string
        hours:
          title: Hours
          description: List of projection hours
          type: array
          items: {}
      required:
      - name
      - hours
    core__api__schemas__policy_analysis__Analysis:
      title: Analysis
      type: object
      properties:
        question:
          title: Question
          description: The question that was asked.
          example: Does the policy detail the website's privacy policy and how the data of customers is protected, used or disclosed?
          type: string
        answer:
          title: Answer
          description: The answer to the question.
          example: 'Yes'
          type: string
        sources:
          title: Sources
          description: The sources of the answer.
          example:
          - https://www.acme.com/privacy
          - https://www.acme.com/privacy2
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 2083
            format: uri
      required:
      - question
      - sources
    HistoricalArchive:
      title: HistoricalArchive
      type: object
      properties:
        url:
          title: URL
          description: The URL to access an archive.
          example: '2021-12-15'
          minLength: 1
          maxLength: 65536
          format: uri
          type: string
        taken_date:
          title: Taken date
          description: The date the archive was captured.
          example: '2021-12-15'
          type: string
          format: date
    RiskIndicators:
      title: RiskIndicators
      type: object
      properties:
        validity:
          title: Validity indicators
          description: A list of data points that indicate the business's legitimacy.
          default: []
          example: []
          type: array
          items:
            $ref: '#/components/schemas/Risk'
        notice:
          title: Notice indicators
          description: A list of data points that indicate information you may want to take heed of before interacting with the business.
          default: []
          example: []
          type: array
          items:
            $ref: '#/components/schemas/Risk'
        risk:
          title: Risk indicators
          description: A list of data points that indicate the risk of interacting with the business.
          default: []
          example: []
          type: array
          items:
            $ref: '#/components/schemas/Risk'
    DataSource:
      title: DataSource
      description: An enumeration.
      enum:
      - website
      - social
      - other
      - submitted
      type: string
    CustomerReviewsData:
      title: CustomerReviewsData
      type: object
      properties:
        provider:
          title: Provider
          description: Unique ID of the review service providing the review data
          type: string
        meta:
          title: Meta
          description: Data describing the review data
          allOf:
          - $ref: '#/components/schemas/CustomerReviewsMeta'
    PhoneLinkType:
      title: PhoneLinkType
      description: An enumeration.
      enum:
      - direct
      - employee
      - address
      type: string
    RiskType:
      title: RiskType
      description: An enumeration.
      enum:
      - Validity
      - Notice
      - Risk
      type: string
    AddressCoordinatesAccuracy:
      title: AddressCoordinatesAccuracy
      description: Order matters here, list from least to most accurate
      enum:
      - APPROXIMATE
      - ROOFTOP
      type: string
    SubmittedDescriptionMatchType:
      title: SubmittedDescriptionMatchType
      description: An enumeration.
      enum:
      - Full match
      - Partial match
      - No match
      type: string
    ReferringSite:
      title: ReferringSite
      type: object
      properties:
        url:
          title: URL
          description: Link to the referring site.
          example: null
          minLength: 1
          maxLength: 65536
          format: uri
          type: string
        traffic_share:
          title: Traffic Share
          description: Share of total traffic coming from the referring traffic.
          example: null
          type: number
        screenshot_image_link:
          title: Screenshot Image
          description: A link to the full website screenshot image.
          example: null
          minLength: 1
          maxLength: 65536
          format: uri
          type: string
    Ecommerce:
      title: Ecommerce
      type: object
      properties:
        platform:
          title: Ecommerce Platform
          description: The ecommerce platform used by the company.
          example: shopify
          type:
          - string
          - 'null'
        product_count:
          title: Product Count
          description: The number of products sold by the company.
          example: 100
          type:
          - integer
          - 'null'
        vendor_count:
          title: Vendor Count
          description: The number of unique vendors sold by the company.
          example: 20
          type:
          - integer
          - 'null'
        average_price:
          title: Average Price
          description: The average price of products for sale, in the currency of the 'currency_code' field.
          example: 15.55
          type:
          - number
          - 'null'
        minimum_price:
          title: Minumum Price
          description: The lowest price of any product for sale, in the currency of the 'currency_code' field.
          example: 9.99
          type:
          - number
          - 'null'
        maximum_price:
          title: Maximum Price
          description: The highest price of any product for sale, in the currency of the 'currency_code' field.
          example: 100.99
          type:
          - number
          - 'null'
        currency_code:
          title: Currency Code
          description: The ISO code for the currency used.
          example: USD
          type:
          - string
          - 'null'
        last_updated_date:
          title: Last Updated Date
          description: The date of the last update to the site.
          example: '2023-03-23'
          type:
          - string
          - 'null'
          format: date
    CompanySize:
      title: CompanySize
      description: An enumeration.
      enum:
      - 1-10
      - 11-50
      - 51-200
      - 201-500
      - 500-1,000
      - 1,001-5,000
      - 5,000+
      type: string
    TooManyRequests:
      title: TooManyRequests
      type: object
      properties:
        message:
          title: Message
          type: string
      required:
      - message
      example:
        message: You have exceeded your current quota of 10 requests/second for this api endpoint.  Please slow down.
    Person:
      title: Person
      type: object
      properties:
        name:
          title: Name
          description: The person's full name.
          maxLength: 1024
          minLength: 1
          example: Dara Khosrowshahi
          type: string
        job_title:
          title: Job title
          description: A name that describes someone's job or position.
          maxLength: 255
          minLength: 1
          example: Chief Executive Officer
          type: string
        linkedin_url:
          title: LinkedIn URL
          description: The person's LinkedIn profile URL.
          maxLength: 1024
          minLength: 29
          example: https://www.linkedin.com/in/dara-khosrowshahi-9b1a8b/
          type: string
        profile_picture:
          title: LinkedIn photo URL
          description: The URL of the person's LinkedIn profile photo.
          maxLength: 1024
          minLength: 34
          example: https://media.licdn.com/dms/image/D4D03AQGDnwFEps6idg/profile-displayphoto-shrink_200_200/0/1673360179524?e=1688601600&v=beta&t=bpXAkQdRR7liIMck3FQ7maRE-XeMwtChfWt73oB7YZ0
          type: string
        state_province:
          title: State
          description: The state or province where the person is located.
          maxLength: 255
          minLength: 1
          example: California
          type: string
        city:
          title: City
          description: The city where the person is located.
          maxLength: 255
          minLength: 1
          example: San Francisco
          type: string
        country:
          title: Country
          description: The country where the person is located.
          maxLength: 255
          minLength: 1
          example: United States
          type: string
        start_date:
          title: Start date
          description: The date the person started at the company.
          example: '1995-07-14'
          type:
          - string
          - 'null'
          format: date
        other_active_positions:
          title: Other active positions
          description: Other jobs listed as currently active.
          example: '[{"title": "CEO", "company_name": "ACME LLC.", "start_date": "2018-09-01"}]'
          type:
          - array
          - 'null'
          items:
            $ref: '#/compone

# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/truebiz/refs/heads/main/openapi/truebiz-web-presence-review-api-openapi.yml