Sigma360 Monitoring: History API

openapi: 3.2.0
info:
  contact:
    email: support@sigma360.com
    name: Sigma Customer Success Team
  description: '### API Concepts

    This API is designed to help you interact and integrate with Sigma360.'
  title: 'Sigma360 Monitoring: History API'
  version: v2.0.1
  x-logo:
    altText: Sigma360
    href: https://sigma360.com
    url: logo.png
servers:
- url: https://api.sigma360.com/external/v2
security:
- apiKey: []
tags:
- description: Retrieving monitoring history
  name: 'Monitoring: History'
paths:
  /entities/histories:
    post:
      description: This endpoint will return a paginated list of all entities' history events. A history event is created whenever an entity's data changes for any reason. Only includes monitored, unarchived entities.
      parameters:
      - description: 'Page number, 1-indexed. Default: 1'
        in: query
        name: page
        schema:
          description: 'Page number, 1-indexed. Default: 1'
          example: 1
          type: integer
      - description: 'Number of results per page. Maximum: 100, Default: 10'
        in: query
        name: pageSize
        schema:
          description: 'Number of results per page. Maximum: 100, Default: 10'
          example: 10
          type: integer
      - in: query
        name: cursor
        schema:
          nullable: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestEntitiesHistoriesRequestPublic'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePaginatedEntityHistory'
          description: OK
        '400':
          content:
            text/plain:
              schema:
                type: string
          description: Bad Request
        '401':
          content:
            text/plain:
              schema:
                type: string
          description: Unauthorized
        '429':
          content:
            text/plain:
              schema:
                type: string
          description: Too Many Requests
        '500':
          content:
            text/plain:
              schema:
                type: string
          description: Internal Server Error
      security:
      - apiKey: []
      summary: Retrieve history events for all entities in a paginated stream
      tags:
      - 'Monitoring: History'
      operationId: postEntitiesHistories
      x-operation-id-source: derived
  /entity/{entityURN}/history:
    post:
      description: This endpoint will return a paginated list of entity history events for a given entity. A history event is created whenever an entity's data changes for any reason.
      parameters:
      - description: 'Page number, 1-indexed. Default: 1'
        in: query
        name: page
        schema:
          description: 'Page number, 1-indexed. Default: 1'
          example: 1
          type: integer
      - description: 'Number of results per page. Maximum: 100, Default: 10'
        in: query
        name: pageSize
        schema:
          description: 'Number of results per page. Maximum: 100, Default: 10'
          example: 10
          type: integer
      - description: The entity ID or URN.
        in: path
        name: entityURN
        required: true
        schema:
          description: The entity ID or URN.
          example: urn:sigma:entity:1234-abcdef
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestEntityHistoryRequestPublic'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePaginatedEntityHistory'
          description: OK
        '400':
          content:
            text/plain:
              schema:
                type: string
          description: Bad Request
        '401':
          content:
            text/plain:
              schema:
                type: string
          description: Unauthorized
        '429':
          content:
            text/plain:
              schema:
                type: string
          description: Too Many Requests
        '500':
          content:
            text/plain:
              schema:
                type: string
          description: Internal Server Error
      security:
      - apiKey: []
      summary: Retrieve a paginated list of entity history events
      tags:
      - 'Monitoring: History'
      operationId: postEntityByEntityURNHistory
      x-operation-id-source: derived
components:
  schemas:
    SigmaidExtractEntity:
      properties:
        entityRisk:
          description: 'A measure of how culpable or involved the entity is in the event, based on the article text. Possible values are: ''Very High'', ''High'', ''Possible'', ''Low'', ''Unlikely'', and ''Undetermined''.'
          type: string
        focalEntity:
          description: Marks if this extracted entity is the main entity of its event. Events have one focal entity, but articles may appear in different events with different focal entities.'
          type: boolean
        highlights:
          description: Offsets of where the entity appears in the article body or title
          items:
            $ref: '#/components/schemas/SigmaidHighLightSection'
          type: array
        labels:
          description: 'Predicted entity types: PER, ORG, LOC, or MISC.'
          items:
            type: string
          nullable: true
          type: array
        text:
          description: The entity name detected in the article body
          type: string
        yearsOfBirth:
          description: Birthdays of entities, if detected. This is a list of years, not a range.
          items:
            type: integer
          nullable: true
          type: array
      type: object
    SigmaidCustomEntityField:
      properties:
        key:
          type: string
        value:
          type: string
      type: object
    ResponseIndicatorDiff:
      properties:
        added:
          type: integer
        category:
          type: string
        deleted:
          type: integer
        isNetwork:
          type: boolean
        maxScore:
          type: integer
        updated:
          type: integer
      type: object
    SigmaidHighLightSection:
      properties:
        end:
          description: The end of the detected entity name in the article. Relative to the beginning of the text.
          type: integer
        start:
          description: The beginning offset of the detected entity name in the article. Relative to the beginning of the text.
          type: integer
        target:
          description: Determines whether the offsets should be applied to the title or body.
          enum:
          - title
          - body
          type: string
      type: object
    ResponseEntityHistory:
      properties:
        changedMatches:
          type: integer
        configurationChanges:
          $ref: '#/components/schemas/ResponseConfigurationChanges'
        currentSearchParams:
          $ref: '#/components/schemas/SigmaidBasicSearchParams'
        event:
          type: string
        externalDocumentLink:
          type: string
        historyID:
          minimum: 0
          type: integer
        indicatorChanges:
          items:
            $ref: '#/components/schemas/ResponseIndicatorChange'
          nullable: true
          type: array
        indicatorChangesSummary:
          items:
            $ref: '#/components/schemas/ResponseIndicatorDiff'
          nullable: true
          type: array
        kycChanges:
          items:
            $ref: '#/components/schemas/ResponseKYCChange'
          nullable: true
          type: array
        matchChanges:
          items:
            $ref: '#/components/schemas/ResponseMatchChange'
          nullable: true
          type: array
        newsChanges:
          items:
            $ref: '#/components/schemas/ResponseNewsChange'
          nullable: true
          type: array
        numIndicators:
          $ref: '#/components/schemas/ResponseDiffNumber'
        numMatches:
          $ref: '#/components/schemas/ResponseDiffNumber'
        origin:
          type: string
        postEventSearchParams:
          $ref: '#/components/schemas/SigmaidBasicSearchParams'
        preEventSearchParams:
          $ref: '#/components/schemas/SigmaidBasicSearchParams'
        riskScore:
          $ref: '#/components/schemas/ResponseDiffNumber'
        timestamp:
          format: date-time
          type: string
        urn:
          type: string
      type: object
    SigmaidRelationshipChain:
      properties:
        edges:
          items:
            $ref: '#/components/schemas/SigmaidEdge'
          nullable: true
          type: array
        entities:
          items:
            $ref: '#/components/schemas/SigmaidBasicEntityResult'
          nullable: true
          type: array
      type: object
    RequestEntitiesHistoriesRequestPublic:
      properties:
        createdAt:
          $ref: '#/components/schemas/RequestDateRangeRequest'
        cursor: {}
        groupIDs:
          description: Optional. An array of group IDs to include entities from.
          items:
            minimum: 0
            type: integer
          nullable: true
          type: array
        historyTypes:
          description: Optional. An array of history types to include. Empty means all.
          enum:
          - lifecycle
          - review
          - alert
          - disposition
          - monitoring
          - configuration
          items:
            type: string
          nullable: true
          type: array
        page:
          description: 'Page number, 1-indexed. Default: 1'
          example: 1
          type: integer
        pageSize:
          description: 'Number of results per page. Maximum: 100, Default: 10'
          example: 10
          type: integer
        total:
          description: Total number of results. Ignored in requests, used in responses.
          example: 15000
          type: integer
      type: object
    RequestEntityHistoryRequestPublic:
      properties:
        page:
          description: 'Page number, 1-indexed. Default: 1'
          example: 1
          type: integer
        pageSize:
          description: 'Number of results per page. Maximum: 100, Default: 10'
          example: 10
          type: integer
        total:
          description: Total number of results. Ignored in requests, used in responses.
          example: 15000
          type: integer
      type: object
    ResponseConfigurationChanges:
      properties:
        dataChangeType:
          type: string
        dataChanges:
          items:
            $ref: '#/components/schemas/ResponseChangedField'
          nullable: true
          type: array
      type: object
    SigmaidBasicSearchParams:
      properties:
        aliases:
          description: Secondary names to perform a search on
          items:
            example: InGen, InGen Corp
            type: string
          nullable: true
          type: array
        countries:
          description: ISO 3166-1 alpha-2
          items:
            example: US
            type: string
          nullable: true
          type: array
        customFields:
          description: Optional. A list of custom fields to be associated with the entity for cross-referencing or disambiguation in alerts and monitoring. Does not affecting risk or matching logic. Each field must have a unique key.
          items:
            $ref: '#/components/schemas/SigmaidCustomEntityField'
          nullable: true
          type: array
        customerKey:
          description: Optional. A user-provided identifier that will be returned in alerts and monitoring. Any format.
          example: ABC1234567890
          type: string
        dob:
          description: Birth or foundation date. YYYY, YYYY-MM, YYYY-MM-DD, YYYY/MM or YYYY/MM/DD format.
          example: '1993-06-11'
          nullable: true
          type: string
        entityName:
          description: The primary name of the search
          example: InGen Corporation
          type: string
        entityType:
          enum:
          - person
          - company
          - aircraft
          - vessel
          example: company
          nullable: true
          type: string
      required:
      - entityName
      type: object
    SigmaidSourcesByIntegration:
      properties:
        key:
          type: string
        lastUpdated:
          format: date-time
          nullable: true
          type: string
        matches:
          items:
            type: string
          nullable: true
          type: array
        matchesOriginated:
          type: integer
        name:
          type: string
        ultimateSources:
          items:
            type: string
          nullable: true
          type: array
      type: object
    SigmaidSummarySearchResultRow:
      properties:
        aliases:
          items:
            example: InGen, InGen Corp
            type: string
          nullable: true
          type: array
        birthDates:
          description: Birth dates of the entity
          items:
            $ref: '#/components/schemas/SigmaidDateWithSource'
          nullable: true
          type: array
        entityName:
          example: InGen Corporation
          type: string
        entityType:
          example: company
          type: string
        foundationDates:
          description: Foundation dates of the entity
          items:
            $ref: '#/components/schemas/SigmaidDateWithSource'
          nullable: true
          type: array
        hasIndirectOwners:
          type: boolean
        hasNetworkConnections:
          type: boolean
        indicatorSummaries:
          items:
            $ref: '#/components/schemas/SigmaidIndicatorSummary'
          nullable: true
          type: array
        locations:
          items:
            $ref: '#/components/schemas/SigmaidLocation'
          nullable: true
          type: array
        matchDOB:
          type: string
        matchLocation:
          type: string
        matchName:
          type: string
        matchStrength:
          type: number
        risk:
          $ref: '#/components/schemas/SigmaidRiskSummary'
        sigmaID:
          example: 3BX869NCJTZ5K
          type: string
        sources:
          items:
            $ref: '#/components/schemas/SigmaidSourcesByIntegration'
          nullable: true
          type: array
      type: object
    ResponseMatchChange:
      properties:
        birthOrFoundationDates:
          items:
            format: date-time
            type: string
          nullable: true
          type: array
        changeType:
          type: string
        entityName:
          type: string
        locations:
          items:
            $ref: '#/components/schemas/SigmaidLocation'
          nullable: true
          type: array
        sigmaID:
          type: string
      type: object
    SigmaidRiskSummary:
      properties:
        score:
          type: number
      type: object
    SigmaidEdge:
      properties:
        edgeID:
          description: A unique identifier for this edge.
          type: string
        extendedRelationshipData:
          $ref: '#/components/schemas/SigmaidExtendedRelationshipData'
        fromNode:
          description: The SigmaID of the node that this edge starts from.
          type: string
        inverseRelationship:
          description: The normalized relationship in the inverse direction.
          example: Is Subsidiary Of
          type: string
        relationship:
          description: The normalized relationship, as determined by SigmaID's NLP models.
          example: Has Subsidiary
          type: string
        relationshipDenotesOwnership:
          description: Whether this relationship imparts ownership or control. For example, 'Has Subsidiary' would have this field set to true, while 'Is Officer Of'' would have it set to false.
          type: boolean
        toNode:
          description: The SigmaID of the node that this edge points to.
          type: string
        unnormalizedRelationship:
          description: The raw text of the relationship as it appears in the source data.
          type: string
      type: object
    SigmaidLocation:
      properties:
        address:
          example: 10 Downing St, London SW1A 2AB, United Kingdom
          type: string
        country:
          example: United Kingdom
          type: string
        countryCode:
          example: GB
          type: string
        fromDate:
          example: '1684-05-20'
          type: string
        locality:
          example: London
          type: string
        majorAdministrativeDivision:
          example: England
          type: string
        minorAdministrativeDivision:
          example: City of Westminster
          type: string
        postalCode:
          example: SW1A 2AB
          type: string
        sourceAttribution:
          description: Not human readable. This can be used to look up against source information objects.
          items:
            example: abcd1234//1234567890
            type: string
          nullable: true
          type: array
        streetName:
          example: Downing St
          type: string
        streetNumber:
          example: '10'
          type: string
        toDate:
          example: '2020-05-20'
          type: string
        type:
          example: Residence
          type: string
      type: object
    SigmaidExtractedRisk:
      properties:
        category:
          type: string
        highlights:
          description: Offsets of where the entity appears in the article body or title
          items:
            $ref: '#/components/schemas/SigmaidHighLightSection'
          type: array
      type: object
    ResponseDiffNumber:
      properties:
        new:
          type: integer
        old:
          type: integer
      type: object
    ResponseNewsChange:
      properties:
        articles:
          items:
            $ref: '#/components/schemas/SigmaidEventArticle'
          nullable: true
          type: array
        changeType:
          type: string
        dataChanges:
          items:
            $ref: '#/components/schemas/ResponseChangedField'
          nullable: true
          type: array
        decisioning:
          $ref: '#/components/schemas/ResponseDecisionState'
        decisioningTimeline:
          items:
            $ref: '#/components/schemas/ResponseDecisionTimelineState'
          nullable: true
          type: array
        entityRisk:
          type: string
        eventConfidence:
          type: number
        eventLabel:
          type: string
        eventMaterialityScore:
          type: number
        eventSeverity:
          type: string
        humanVerified:
          type: boolean
        id:
          type: string
        isPreferredPublisher:
          type: boolean
        sigmaID:
          type: string
        topics:
          items:
            type: string
          nullable: true
          type: array
        unformattedLabel:
          type: string
      type: object
    ResponsePaginatedEntityHistory:
      properties:
        histories:
          items:
            $ref: '#/components/schemas/ResponseEntityHistory'
          nullable: true
          type: array
        page:
          type: integer
        pageSize:
          type: integer
        total:
          type: integer
      type: object
    ResponseDecisionState:
      properties:
        decidedByDefault:
          type: boolean
        decisionedAgainst:
          type: boolean
        hasDecision:
          type: boolean
        notes:
          type: string
        rationale:
          items:
            type: string
          nullable: true
          type: array
        reviewSubmittedAt:
          type: string
        reviewedByUserName:
          type: string
        reviewedByUserURN:
          type: string
        wasDecisionMadeAgainstThisVersion:
          type: boolean
      type: object
    SigmaidIndicatorSummary:
      properties:
        category:
          example: Sanctions
          type: string
        count:
          example: 2
          type: integer
        isNetwork:
          description: Indicates whether the indicator is describes this entity or one of its network connections
          example: false
          type: boolean
        maxScore:
          example: 100
          type: integer
      type: object
    ResponseKYCChange:
      properties:
        changeType:
          type: string
        dataChanges:
          items:
            $ref: '#/components/schemas/ResponseChangedField'
          nullable: true
          type: array
        sigmaID:
          type: string
      type: object
    SigmaidEventArticle:
      properties:
        articleHash:
          type: string
        body:
          description: The full-text article body, if available
          type: string
        extractedEntities:
          description: Detected entities and highlights from the article body/title. This can be natural persons or entities.
          items:
            $ref: '#/components/schemas/SigmaidExtractEntity'
          nullable: true
          type: array
        extractedRisks:
          description: Highlight information for risky keywords or phrases in the article or title.
          items:
            $ref: '#/components/schemas/SigmaidExtractedRisk'
          type: array
        extractedTerritories:
          description: Countries and major administrative divisions (e.g., states, provinces) mentioned in the article.
          items:
            $ref: '#/components/schemas/SigmaidExtractedTerritory'
          nullable: true
          type: array
        humanVerified:
          description: A small portion of articles have been manually verified by Sigma360 analysts, this field indicates whether the article has been verified adverse or not
          type: boolean
        isPreferredPublisher:
          description: High-quality government gazettes, newspapers of record, or reputable news agencies are listed as preferred publishers. This field indicates whether the article is from a preferred publisher
          type: boolean
        language:
          description: The ISO 639-1 two-letter language code of the article
          type: string
        materialityScore:
          description: A ranking of how severe the event is, based on the article text. This is a number between 0 and 1, where 1 is the most severe.
          type: number
        publishedDate:
          description: The date and time the article was published, in ISO 8601 format
          format: date-time
          type: string
        publisher:
          description: A human-readable name of the publisher
          example: New York Times
          type: string
        publisherCountryCode:
          description: The ISO 3166-1 alpha-2 country code of the publisher's country. This is not the country of the event or journalist, but the country of the publisher's headquarters
          type: string
        title:
          description: The article title
          type: string
        topics:
          description: A list of detected event topics, such as 'white_collar_crime'
          items:
            type: string
          nullable: true
          type: array
        url:
          description: The article URL
          type: string
      type: object
    SigmaidExtractedTerritory:
      properties:
        adminOne:
          description: The first-level administrative division of the territory, if applicable. For example, a state in the US or a province in Canada.
          nullable: true
          type: string
        count:
          description: The amount of times this territory was mentioned in the article
          type: integer
        country:
          description: The ISO 3166-1 alpha-2 country code of the territory
          type: string
        evidence:
          description: The snippets of the article that support a territory determination
          items:
            type: string
          nullable: true
          type: array
        highlights:
          description: Offsets of where the entity appears in the article body or title
          items:
            $ref: '#/components/schemas/SigmaidHighLightSection'
          type: array
      type: object
    ResponseChangedField:
      properties:
        after:
          items:
            $ref: '#/components/schemas/ResponseChangedItem'
          nullable: true
          type: array
        before:
          items:
            type: string
          nullable: true
          type: array
        field:
          type: string
      type: object
    SigmaidDateWithSource:
      properties:
        humanReadable:
          description: A human-readable representation of the range. Show in user interfaces instead of the date range if present
          example: Circa 1980
          nullable: true
          type: string
        sourceAttribution:
          description: Not human readable. This can be used to look up against source information objects.
          items:
            example: abcd1234//1234567890
            type: string
          nullable: true
          type: array
        until:
          description: If the date is a range, the end of the range
          example: '2023-01-01T00:00:00Z'
          format: date-time
          nullable: true
          type: string
        value:
          description: The date, or the start of a date range
          example: '2023-01-01T00:00:00Z'
          format: date-time
          type: string
      type: object
    ResponseDecisionTimelineState:
      properties:
        decidedByDefault:
          type: boolean
        decisionedAgainst:
          type: boolean
        notes:
          type: string
        rationale:
          items:
            type: string
          nullable: true
          type: array
        reviewSubmittedAt:
          type: string
        reviewedByUserName:
          type: string
        reviewedByUserURN:
          type: string
      type: object
    SigmaidSourceURL:
      properties:
        name:
          type: string
        url:
          nullable: true
          type: string
      type: object
    ResponseIndicatorChange:
      properties:
        category:
          example: Sanctions
          type: string
        causalSigmaID:
          $ref: '#/components/schemas/SigmaidSummarySearchResultRow'
        changeType:
          type: string
        code:
          example: SAN006
          type: string
        dataChanges:
          items:
            $ref: '#/components/schemas/ResponseChangedField'
          nullable: true
          type: array
        date:
          example: '2023-01-01T00:00:00Z'
          format: date-time
          nullable: true
          type: string
        decisioning:
          $ref: '#/components/schemas/ResponseDecisionState'
        decisioningTimeline:
          items:
            $ref: '#/components/schemas/ResponseDecisionTimelineState'
          nullable: true
          type: array
        description:
          example: Swiss State Secretariat for Economic Affairs
          type: string
        extras:
          additionalProperties:
            items:
              type: string
            type: array
          description: Extra details about the indicator
          nullable: true
          type: object
        hopsAway:
          example: 0
          type: integer
        name:
          example: Appears on sanction list
          type: string
        originatingSigmaID:
          type: string
        possibleSameAs:
          type: string
        primaryExtras:
          additionalProperties:
            items:
              type: string
            type: array
          description: Extra details about the indicator, typical shown above the fold
          nullable: true
          type: object
        relationshipChain:
          $ref: '#/components/schemas/SigmaidRelationshipChain'
        score:
          example: 90
          type: integer
        sourceAttribution:
          description: Not human readable. This can be used to look up against source information objects.
          items:
            example: abcd1234//1234567890
            type: string
          nullable: true
          type: array
        sources:
          items:
            $ref: '#/components/schemas/SigmaidSourceURL'
          nullable: true
          type: array
        subcategory:
          example: sanctions_swiss
          type: string
        urn:
          example: urn:sigma:indicator:5VpYSbsw2R6UaVxFilHv_TpJ5wJZocEzMAaLvFkVJAg=
          type: string
      required:
      - urn
      - code
      - name
      - category
      - subcategory
      - hopsAway
      - sources
      - description
      type: object
    SigmaidExtendedRelationshipData:
      properties:
        asOfDate:
          description: The date this relationship data was reported as of.
          type: string
        currency:
          description: The currency of the monetary value.
          type: string
        endDate:
          description: The date this relationship ended.
          type: string
        former:
          description: Whether this relationship is no longer active.
          type: boolean
        monetaryValue:
          description: The monetary value associated with this relationship.
          type: string
        numShares:
          description: The number of shares held in this relationship.
          type: string
        percent:
          description: The ownership or control percentage associated with this relationship.
          type: string
        startDate:
          description: The date this relationship began.
          type: string
        ultimateSources:
          description: The original data sources for this relationship.
          items:
            type: string
          nullable: true
          type: array
      type: object
    ResponseChangedItem:
      properties:
        type:
          type: string
        value:
          type: string
      type: object
    RequestDateRangeRequest:
      properties:
        since:
          description: The start of the date range.
          example: '2023-01-01T00:00:00Z'
          format: date-time
          nullable: true
          type: string
        until:
          description: The end of the date range.
          example: '2023-01-01T00:00:00Z'
          format: date-time
          nullable: true
          type: string
      type: object
    SigmaidBasicEntityResult:
      properties:
        entityName:
          example: InGen Corporation
          type: string
        entityType:
          example: company
          type: string
        sigmaID:
          example: 3BX869NCJTZ5K
          type: string
      type: object
  securitySchemes:
    apiKey:
      description: API Key
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  description: Sigma360 Product Information
  url: https://sigma360.com