Interos Organizations API

openapi: 3.0.2
info:
  title: Interos Groups Organizations API
  version: 1.0.0
  description: This API uses location data provided by https://geocode.earth/
  x-logo: https://www.interos.ai/wp-content/uploads/2019/12/logo_blue-black-1.png
servers:
- url: https://api.interos.ai
security:
- Interos API Key: []
- Interos Customer ID: []
tags:
- name: Organizations
paths:
  /v1/organizations/search_lite:
    get:
      description: Search organizations by name, duns, cage code, ueid or interos id with optional country filter
      operationId: get_organizations_search_lite_v1_external_organizations_search_lite_get
      parameters:
      - description: Search term to match against organization names, duns, cage code, ueid or interos id
        in: query
        name: search_term
        required: true
        schema:
          description: Search term to match against organization names, duns, cage code, ueid or interos id
          title: Search Term
          type: string
      - description: Optional ISO country code to filter results
        in: query
        name: country_code
        required: false
        schema:
          description: Optional ISO country code to filter results
          nullable: true
          title: Country Code
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/OrganizationSearchLiteResult'
                title: Response Get Organizations Search Lite
                type: array
          description: Succeeded
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: Forbidden Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Search organizations by name with optional country filter
      tags:
      - Organizations
  /v1/organizations/{organization_id}:
    get:
      description: Get the profile for an organization
      operationId: get_organization_profile_v1_external_organizations__organization_id__get
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          format: uuid
          title: The ID of organization to get profile for
          type: string
      - description: DEPRECATED. Use include=risk_details instead
        in: query
        name: include_risk_variables
        required: false
        schema:
          default: false
          description: DEPRECATED. Use include=risk_details instead
          title: Include Risk Variables
          type: boolean
      - description: DEPRECATED. Use include=risk_details instead
        in: query
        name: include_attributes
        required: false
        schema:
          default: false
          description: DEPRECATED. Use include=risk_details instead
          title: Include Attributes
          type: boolean
      - description: 'Comma separated list of expandable data to include. Valid values:

          * `locations`: returns **_locations_** array with all locations for the organization

          * `groups`: returns **_group_info_** array with group membership for the organization and customer

          * `product_categories`: returns **_product_categories_bought_** and **_product_categories_sold_** arrays with product categories and last observed dates for the organization

          * `restrictions`: returns **_restrictions_** array with restricted lists on which an organization appears

          * `risk_overview`: returns **_risk_profile_** object with iScore and risk factor scores

          * `detailed_risk`: returns **_risk_profile_** object with iScore, risk factor scores, risk sub-factor* scores and attributes* (*unlocked organizations only)


          Example: `?include=locations,groups`'
        in: query
        name: include
        required: false
        schema:
          default: risk_overview
          description: 'Comma separated list of expandable data to include. Valid values:

            * `locations`: returns **_locations_** array with all locations for the organization

            * `groups`: returns **_group_info_** array with group membership for the organization and customer

            * `product_categories`: returns **_product_categories_bought_** and **_product_categories_sold_** arrays with product categories and last observed dates for the organization

            * `restrictions`: returns **_restrictions_** array with restricted lists on which an organization appears

            * `risk_overview`: returns **_risk_profile_** object with iScore and risk factor scores

            * `detailed_risk`: returns **_risk_profile_** object with iScore, risk factor scores, risk sub-factor* scores and attributes* (*unlocked organizations only)


            Example: `?include=locations,groups`'
          title: Include
          type: string
      - description: "\nLevel of firmographics to include:\n* basic: id, name, url, country code, iScore\n* detailed: all available firmographics\n               "
        in: query
        name: detail_level
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/OrganizationDetailLevel'
          default: detailed
          description: "\nLevel of firmographics to include:\n* basic: id, name, url, country code, iScore\n* detailed: all available firmographics\n               "
      - description: Enables per entity restrictions attributes and removes restrictions scores
        in: query
        name: enable_restrictions_update
        required: false
        schema:
          default: false
          description: Enables per entity restrictions attributes and removes restrictions scores
          title: Enable Restrictions Update
          type: boolean
      - description: Enables recalibrated iScore levels
        in: query
        name: enable_iscore_update
        required: false
        schema:
          default: false
          description: Enables recalibrated iScore levels
          title: Enable iScore Update
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized Response
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: Forbidden Response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not Found Error
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Organization Profile
      tags:
      - Organizations
components:
  schemas:
    ScoreLevel:
      description: An enumeration.
      enum:
      - Low
      - Medium
      - High
      - Extreme
      - 'No'
      title: ScoreLevel
      type: string
    RiskAttribute:
      properties:
        description:
          title: Description
          type: string
        display_value:
          title: Display Value
          type: string
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        source_name:
          title: Source Name
          type: string
        source_url:
          title: Source Url
          type: string
        value:
          title: Value
          type: string
      required:
      - key
      - label
      title: RiskAttribute
      type: object
    Segment:
      description: An enumeration.
      enum:
      - Firm
      - Country
      - Industry
      title: Segment
      type: string
    ForbiddenError:
      properties:
        detail:
          title: Detail
          type: string
      title: ForbiddenError
      type: object
    RestrictedList:
      properties:
        list_category:
          nullable: true
          title: List Category
          type: string
          description: Label under which the Restrictions list is categorized
        list_description:
          nullable: true
          title: List Description
          type: string
          description: Short description of the Restrictions list
        list_id:
          format: uuid
          title: List Id
          type: string
          description: Interos unique ID for the Restrictions list
        list_key:
          nullable: true
          title: List Key
          type: string
          description: (Unused)
        list_name:
          title: List Name
          type: string
          description: Short name of the Restrictions list
        list_segment:
          allOf:
          - $ref: '#/components/schemas/Segment'
          default: Firm
          description: Indicates whether the Restrictions list applies to the organization or primary country
        list_source_url:
          nullable: true
          title: List Source Url
          type: string
          description: URL to where the Restrictions list can be accessed
        list_additional_context:
          nullable: true
          title: List Additional Context
          type: string
          description: Description that explains why the company is on a restrictions list
        list_first_added_date:
          nullable: true
          title: List First Added Date
          type: string
          description: The date a company was first added to a restrictions list
        list_removed_date:
          nullable: true
          title: List Removed Date
          type: string
          description: The date a company was removed from a restrictions list
        list_last_observed_date:
          nullable: true
          title: List Last Observed Date
          type: string
          description: The date a company's listing was most recently updated
        list_active_status:
          nullable: true
          title: List Active Status
          type: boolean
          description: Indicator to identify if a restriction is active or not
      required:
      - list_id
      - list_name
      title: RestrictedList
      type: object
    Address:
      properties:
        city:
          title: City
          type: string
          description: City of the organization's branch location
        country_code:
          title: Country Code
          type: string
          description: 3 digit country code of organization's branch location
        is_primary:
          title: Is Primary
          type: boolean
          description: Not used - see ultimate_parent fields
        latitude:
          title: Latitude
          type: number
          description: Latitude of organization's branch location
        longitude:
          title: Longitude
          type: number
          description: Longitude of organization's branch location
        postal_code:
          title: Postal Code
          type: string
          description: Postal code of organization's branch location
        province:
          title: Province
          type: string
          description: Province of organization's branch location
        street_address:
          title: Street Address
          type: string
          description: Street address of organization's branch location (Line 1)
        street_address_2:
          title: Street Address 2
          type: string
          description: Street address of organization's branch location (Line 2)
      title: Address
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    ProductCategory:
      properties:
        product_category_name:
          title: Product Cateogry Name
          type: string
          description: Product category name
        last_observed_date:
          title: Last Observed Date
          type: string
          description: Most recent date when this organization was observed to have bought or sold this product category
      title: ProductCategory
      type: object
    OrganizationGroupBase:
      properties:
        group_id:
          format: uuid
          title: Group Id
          type: string
          description: Unique identifier of the customer defined group
        name:
          title: Name
          type: string
          description: Name of the customer defined group
      required:
      - group_id
      - name
      title: OrganizationGroupBase
      type: object
    RiskVariableScore:
      properties:
        attributes:
          items:
            $ref: '#/components/schemas/RiskAttribute'
          nullable: true
          title: Attributes
          type: array
        description:
          nullable: true
          title: Description
          type: string
        label:
          title: Label
          type: string
        level:
          $ref: '#/components/schemas/ScoreLevel'
        name:
          title: Name
          type: string
        score:
          title: Score
          type: integer
        segment:
          title: Segment
          type: string
        timestamp:
          format: date-time
          title: Timestamp
          type: string
      required:
      - name
      - label
      - timestamp
      title: RiskVariableScore
      type: object
    RiskFactorScore:
      properties:
        description:
          nullable: true
          title: Description
          type: string
          description: Short description of the Risk Factor this data supports
        label:
          title: Label
          type: string
          description: Overarching label that is given to the Risk Factor
        level:
          $ref: '#/components/schemas/ScoreLevel'
          description: Level of risk that the Risk Factor data presents to the organization
        name:
          title: Name
          type: string
          description: 'Name of Risk Factor this data supports: Cyber, Finance, ESG, Geopolitical, Operations, or Restrictions'
        risk_variables:
          items:
            $ref: '#/components/schemas/RiskVariableScore'
          nullable: true
          title: Risk Variables
          type: array
        score:
          title: Score
          type: integer
        timestamp:
          format: date-time
          title: Timestamp
          type: string
        count_restriction_lists:
          nullable: true
          title: Count Restriction Lists
          type: integer
          description: Count of current active restriction lists (only for the restrictions risk factor)
      required:
      - level
      - name
      - timestamp
      title: RiskFactorScore
      type: object
    UnauthorizedError:
      properties:
        message:
          title: Detail
          type: string
      title: UnauthorizedError
      type: object
    Organization:
      properties:
        country_code:
          nullable: true
          title: Country Code
          type: string
          description: 3 digit country code of organization's primary location
        description:
          nullable: true
          title: Description
          type: string
          description: Short description of organization
        description_long:
          nullable: true
          title: Description Long
          type: string
          description: Expanded description of organization
        founding_date:
          format: date
          nullable: true
          title: Founding Date
          type: string
          description: Date on which organization was founded
        group_info:
          items:
            $ref: '#/components/schemas/OrganizationGroupBase'
          nullable: true
          title: Group Info
          type: array
        industry:
          nullable: true
          title: DEPRECATED Industry
          type: string
          description: DEPRECATED NAICS industry name
        industry_category_code:
          nullable: true
          title: Industry Category Code
          type: string
          description: Industry Category Code
        industry_category_name:
          nullable: true
          title: Industry Category Name
          type: string
          description: Industry Category Name
        industry_naics_code:
          nullable: true
          title: Industry NAICS Code
          type: string
          description: Industry NAICS Code
        industry_naics_name:
          nullable: true
          title: Industry NAICS Name
          type: string
          description: Industry NAICS Name
        industry_sic_code:
          nullable: true
          title: Industry SIC Code
          type: string
          description: Industry SIC Code
        industry_sic_name:
          nullable: true
          title: Industry SIC Name
          type: string
          description: Industry SIC Name
        is_pr:
          nullable: true
          title: Is Pr
          type: boolean
          description: True if organization is on any Restrictions lists
        is_unlocked:
          nullable: true
          title: Is Unlocked
          type: boolean
          description: Indicates if organization is unlocked for the accessing customer
        locations:
          items:
            $ref: '#/components/schemas/Address'
          nullable: true
          title: Locations
          type: array
        name:
          title: Name
          type: string
          description: Official legal name of organization
        organization_id:
          format: uuid
          title: Organization Id
          type: string
          description: Unique Interos identifier of organization
        new_organization_id:
          nullable: true
          format: uuid
          title: New Organization Id
          type: string
          description: (New) Unique Interos identifier of organization, if the current `organization_id` is deprecated
        primary_cage_code:
          nullable: true
          title: Primary Cage Code
          type: string
          description: Primary CAGE Code of the organization
        primary_duns_number:
          nullable: true
          title: Primary Duns Number
          type: string
        primary_location:
          allOf:
          - $ref: '#/components/schemas/Address'
          nullable: true
          title: Primary Location
        product_categories_bought:
          items:
            $ref: '#/components/schemas/ProductCategory'
          nullable: true
          title: Product Categories Bought
          type: array
          description: List of product categories bought and last observed dates associated with this organization, ordered by last observed date
        product_categories_sold:
          items:
            $ref: '#/components/schemas/ProductCategory'
          nullable: true
          title: Product Categories Sold
          type: array
          description: List of product categories sold and last observed dates associated with this organization, ordered by last observed date
        profile_link:
          nullable: true
          title: Profile Link
          type: string
          description: URL to the organization's Interos profile
        restrictions:
          items:
            $ref: '#/components/schemas/RestrictedList'
          nullable: true
          title: Restrictions
          type: array
        risk_profile:
          allOf:
          - $ref: '#/components/schemas/RiskProfile'
          nullable: true
          title: Risk Profile
        risk_score:
          allOf:
          - $ref: '#/components/schemas/IScore'
          nullable: true
          title: Risk Score
        ultimate_parent_id:
          nullable: true
          title: Ultimate Parent Id
          type: string
          description: Unique Interos identifier of ultimate parent
        ultimate_parent_name:
          nullable: true
          title: Ultimate Parent Name
          type: string
          description: Official legal name of ultimate parent
        ultimate_parent_country_code:
          nullable: true
          title: Ultimate Parent Country Code
          type: string
          description: 3 digit country code of ultimate parent's primary location
        updated_date:
          format: date-time
          nullable: true
          title: Updated Date
          type: string
          description: Last time the organization was updated
        url:
          nullable: true
          title: Url
          type: string
          description: Homepage URL of organization
      required:
      - organization_id
      - name
      title: Organization
      type: object
    OrganizationDetailLevel:
      description: An enumeration.
      enum:
      - detailed
      - basic
      title: OrganizationDetailLevel
      type: string
    IScore:
      properties:
        level:
          $ref: '#/components/schemas/ScoreLevel'
        score:
          title: Score
          type: integer
      title: IScore
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    RiskProfile:
      properties:
        overall:
          $ref: '#/components/schemas/Score'
        risk_factors:
          items:
            $ref: '#/components/schemas/RiskFactorScore'
          title: Risk Factors
          type: array
      required:
      - overall
      title: RiskProfile
      type: object
    OrganizationSearchLiteResult:
      properties:
        id:
          format: uuid
          title: Id
          type: string
        name:
          nullable: true
          title: Name
          type: string
        url:
          nullable: true
          title: Url
          type: string
        city:
          nullable: true
          title: City
          type: string
        province:
          nullable: true
          title: Province
          type: string
        country_code:
          nullable: true
          title: Country Code
          type: string
        street_address:
          nullable: true
          title: Street Address
          type: string
        street_address_2:
          nullable: true
          title: Street Address 2
          type: string
        postal_code:
          nullable: true
          title: Postal Code
          type: string
        duns:
          items:
            type: string
          nullable: true
          title: Duns
          type: array
        cage_code:
          items:
            type: string
          nullable: true
          title: Cage Code
          type: array
        ueid:
          items:
            type: string
          nullable: true
          title: Ueid
          type: array
      required:
      - id
      title: OrganizationSearchLiteResult
      type: object
    HTTPError:
      properties:
        detail:
          title: Detail
          type: string
      required:
      - detail
      title: HTTPError
      type: object
    Score:
      properties:
        description:
          nullable: true
          title: Description
          type: string
        label:
          title: Label
          type: string
        level:
          $ref: '#/components/schemas/ScoreLevel'
        name:
          title: Name
          type: string
        score:
          title: Score
          type: integer
        timestamp:
          format: date-time
          title: Timestamp
          type: string
      required:
      - name
      - label
      - timestamp
      title: Score
      type: object
  securitySchemes:
    Interos API Key:
      in: header
      name: x-api-key
      type: apiKey
    Interos Customer ID:
      in: header
      name: x-customer-id
      type: apiKey