Sigma360 Webhooks 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 Webhooks 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: Webhooks that notify you of important events
  name: Webhooks
paths: {}
webhooks:
  Entity Created:
    post:
      tags:
      - Webhooks
      summary: Fires when an Entity Creation Job completes
      description: After using the enqueue bulk entity creation endpoint through the API, or after a user begins an Entity creation job in the Sigma360 interface, this webhook will be triggered when the job completes. Entity creation jobs are atomic. If any entities could not be created, none of the entities are created. The response contains a list of entities that failed during creation, if any were present. If success is false, no entities were created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseTaskCompletionReportPing'
      responses: {}
      security:
      - apiKey: []
  Entity Disposition Changed:
    post:
      tags:
      - Webhooks
      summary: Fires when a Monitored Entity's disposition is changed by a user
      description: When a user changes the disposition of a monitored entity, this webhook will be triggered. Dispositions are the user's determinations to the final state of an entity, such as 'Cleared' or 'Blocked'.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseEntityDispositionChangePing'
      responses: {}
      security:
      - apiKey: []
  History Updated:
    post:
      tags:
      - Webhooks
      summary: Fires when a Monitored Entity updates
      description: When a monitored entity has a data update for any reason, this webhook will be triggered. History updates may describe decisions, reviews, or updates from underlying data sources or statistical models.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseEntityHistoryPing'
      responses: {}
      security:
      - apiKey: []
  New Case Management Entry:
    post:
      tags:
      - Webhooks
      summary: Fires when a user sends an entity to an external case management system
      description: In some configurations, users can send entities to an external case management system for review and action. When this occurs, this webhook will be triggered, allowing you to synchronize your case management system with Sigma360.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseCaseManagementIntentPing'
      responses: {}
      security:
      - apiKey: []
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
    ResponseEntityDispositionWebhookPayload:
      properties:
        customerKey:
          description: A user-provided identifier. Any format.
          example: ABC1234567890
          type: string
        entityURN:
          description: The primary identifier for user-created entities
          example: urn:sigma:entity:123e4567-e89b-12d3-a456-426614174000
          type: string
        newEntityDispositionState:
          description: The new disposition state assigned to the entity
          example: pending
          type: string
        timestamp:
          description: The time when the disposition was changed
          example: '2020-01-01T00:00:00Z'
          format: date-time
          nullable: true
          type: string
        userName:
          description: The name of the user who changed the disposition
          example: John Hammond
          type: string
      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
    ResponseTaskCompletionReport:
      properties:
        apiKey:
          type: string
        numEntities:
          type: integer
        success:
          type: boolean
        taskID:
          type: string
      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
    ResponseEntityHistoryPing:
      properties:
        eventPayload:
          $ref: '#/components/schemas/ResponseEntityHistory'
        eventType:
          default: entity_history
          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
    ResponseEntityDispositionChangePing:
      properties:
        eventPayload:
          $ref: '#/components/schemas/ResponseEntityDispositionWebhookPayload'
        eventType:
          default: entityDispositionChangePing
          type: string
      type: object
    ResponseCaseManagementIntentPing:
      properties:
        eventPayload:
          $ref: '#/components/schemas/ResponseCaseManagementIntentPayload'
        eventType:
          default: sendToCaseManagementIntentPing
          type: string
      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
    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
    ResponseTaskCompletionReportPing:
      properties:
        eventPayload:
          $ref: '#/components/schemas/ResponseTaskCompletionReport'
        eventType:
          default: task_completion
          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
    ResponseCaseManagementIntentPayload:
      properties:
        customFields:
          description: User-provided metadata, any format. Does not affect matching, risk, or profile data.
          items:
            $ref: '#/components/schemas/SigmaidCustomEntityField'
          nullable: true
          type: array
        customerKey:
          description: A user-provided identifier. Any format.
          example: ABC1234567890
          type: string
        entityLink:
          description: The URL link for the specified entity
          example: https://app.sigma360.com/entity/123e4567-e89b-12d3-a456-426614174000
          type: string
        entityURN:
          description: The primary identifier for user-created entities
          example: urn:sigma:entity:123e4567-e89b-12d3-a456-426614174000
          type: string
        indicatorSummaries:
          description: The list of indicator summaries of the entity
          items:
            $ref: '#/components/schemas/SigmaidIndicatorSummary'
          nullable: true
          type: array
        searchParameters:
          $ref: '#/components/schemas/SigmaidBasicSearchParams'
      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