openapi: 3.0.2
info:
  title: Interos Groups 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: Groups
paths:
  /v1/organization_groups:
    get:
      description: Get a list of organization groups for a customer
      operationId: get_all_for_customer_v1_external_organization_groups_get
      parameters:
      - description: 'Used to limit the number of records returned. Default: 100. Max: 500'
        in: query
        name: limit
        required: false
        schema:
          default: 100
          description: 'Used to limit the number of records returned. Default: 100. Max: 500'
          exclusiveMinimum: 0.0
          maximum: 500.0
          title: Limit
          type: integer
      - description: Identifies where to start the pagination block and should not be sent on the initial request.
        in: query
        name: next
        required: false
        schema:
          description: Identifies where to start the pagination block and should not be sent on the initial request.
          title: Next
          type: string
      - description: Return total number of affected records. Only valid on the initial request.
        in: query
        name: return_count
        required: false
        schema:
          default: false
          description: Return total number of affected records. Only valid on the initial request.
          title: Return Count
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationGroupList'
          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 All Groups For Customer
      tags:
      - Groups
  /v1/organization_groups/{group_id}/organizations:
    get:
      description: Get a paginated lists of organizations in a group
      operationId: get_organizations_for_group_v1_external_organization_groups__group_id__organizations_get
      parameters:
      - in: path
        name: group_id
        required: true
        schema:
          format: uuid
          title: Group Id
          type: string
      - description: 'Used to limit the number of records returned. Default: 100. Max: 500'
        in: query
        name: limit
        required: false
        schema:
          default: 100
          description: 'Used to limit the number of records returned. Default: 100. Max: 500'
          exclusiveMinimum: 0.0
          maximum: 500.0
          title: Limit
          type: integer
      - description: Identifies where to start the pagination block and should not be sent on the initial request.
        in: query
        name: next
        required: false
        schema:
          description: Identifies where to start the pagination block and should not be sent on the initial request.
          title: Next
          type: string
      - description: Return total number of affected records. Only valid on the initial request.
        in: query
        name: return_count
        required: false
        schema:
          default: false
          description: Return total number of affected records. Only valid on the initial request.
          title: Return Count
          type: boolean
      - 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
      - description: Only return organizations updated after this ISO 8601 timestamp (e.g. 2026-06-01T00:00:00Z). Timezone offsets are honored; a value with no offset is treated as UTC. The comparison is strictly after. If omitted, all organizations in the group are returned.
        in: query
        name: updated_after
        required: false
        schema:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Only return organizations updated after this timestamp. If omitted, all organizations in the group are returned.
          title: Updated After
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationList'
          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 Organizations For Group
      tags:
      - Groups
components:
  schemas:
    ScoreLevel:
      description: An enumeration.
      enum:
      - Low
      - Medium
      - High
      - Extreme
      - 'No'
      title: ScoreLevel
      type: string
    OrganizationList:
      properties:
        data:
          default: []
          items:
            $ref: '#/components/schemas/Organization'
          title: Data
          type: array
        next:
          title: Next
          type: string
        total_count:
          title: Total Count
          type: integer
      title: PaginatedList[Organization]
      type: object
    OrganizationGroupList:
      properties:
        data:
          default: []
          items:
            $ref: '#/components/schemas/OrganizationGroup'
          title: Data
          type: array
        next:
          title: Next
          type: string
        total_count:
          title: Total Count
          type: integer
      title: PaginatedList[OrganizationGroup]
      type: object
    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
    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
    OrganizationGroup:
      properties:
        created_date:
          format: date-time
          title: Created Date
          type: string
        customer_id:
          title: Customer Id
          type: string
        description:
          title: Description
          type: string
        group_id:
          format: uuid
          title: Group Id
          type: string
        is_my_ecosystem_group:
          title: Is My Ecosystem Group
          type: boolean
        is_unlocked_orgs_group:
          title: Is Unlocked Orgs Group
          type: boolean
        name:
          title: Name
          type: string
        organization_count:
          default: 0
          title: Organization Count
          type: integer
      required:
      - group_id
      - customer_id
      - name
      - created_date
      - is_my_ecosystem_group
      - is_unlocked_orgs_group
      title: OrganizationGroup
      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