Sigma360 Monitoring: Entity Management API

openapi: 3.2.0
info:
  contact:
    email: support@sigma360.com
    name: Sigma Customer Success Team
  description: "### API Concepts\nThis API is designed to help you interact and integrate with Sigma360. You can use it to create new entities, receive notifications about changes to your entities, and retrieve information about your entities. All aspects of a Sigma360 entity can be retrieved through this API.\n\n#### Screening\nScreening identifies: risks, KYC details, news and other critical information based on the provided entity name. The results returned are determined by the pre-defined Filter Set (See below for more details).  \n\n##### Monitoring\nMonitoring will perform a continuous, ongoing screening function, where you can expect to receive alerts and updates about changes to your entities without needing to manually trigger a screening event.\nAn entity is under continuous monitoring if it appears in the 'Monitoring' tab and is not archived. Archiving an entity will suppress all alerts and updates for that entity.\n\n##### Alerts\nAlerts are discreet work items that bring a detected risk to an analyst's attention. You can find alerts in the UI's 'Alerts' tab. \nEvery monitored entity will create alerts as risks are detected. When you are performing a one-off screen, you can specify whether or not you want durable, UI-visible alerts to be created. Alerts created in this way will be visible together with alerts created through monitoring. \n\n\n#### Webhooks\nSeveral events will fire an out-of-band request back to your systems to inform you of data changes or allow you to take action.\n1. Entity Updated - changes to Matches, Indicators, KYC data or News\n2. Entity Creation Finished - a bulk entity creation job has completed\n\nNote that all Webhooks fire against a url provided by you during onboarding. If you need to change this url, please contact Sigma Customer Success.\n\n#### Filter Sets\nMonitoring and screening both use Filter Sets to configure returns and manage true and false positives according to organizational risk appetite.\nFor detailed information on ‘Filter Sets’ - contact Support: [support\\@sigmaratings.com](mailto:support\\@sigmaratings.com).\nScreening response data is organized by: Indicators, News and KYC details. \nFor more information on Indicators, News and KYC data see:[Sigma360 Indicators & Global Data](https://6879283.fs1.hubspotusercontent-na1.net/hubfs/6879283/02%20Product%20Documents/Sigma360%20Indicators%20&%20Global%20Data.pdf). \n\n\n#### Conventions and Definitions\nAll entities are identified by a unique Sigma360 Entity ID (URN). These are stable over the entire lifetime of the entity.\n\nAll dates are expected in RFC3339 format or part thereof, e.g. \"2006-01-02T15:04:05Z07:00\".\n\nAll countries are expected to be in [ISO 3166-1 alpha-2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements), e.g. \"US\", or \"GB\".\nIn general, when a filter is not specified, the default is to return all entities for that field.\n\n##### Rate Limiting\nBy default, we impose a maximum of 100 requests per second per account. If you exceed this limit, you will receive a 429 response codes for the extra requests.\nWe encourage you to aggressively retry requests that were rate-limited, as these do not count against the limit. The limits \ndo not carry over and do not have any memory of previous rate limit events. If you are consistently hitting rate limits, please contact Sigma Customer Success.\n\n##### UI Only tasks\nCertain administrative tasks are limited to the UI and are not available via API. These are:\n1. Creation and maintenance of Filter Sets\n2. Changing the group of one or more entities\n3. Changing the Filter Set for one ore more entities\n4. Review workflow\n"
  title: 'Sigma360 Monitoring: Entity Management 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: Browsing and retrieving monitored entities
  name: 'Monitoring: Entity Management'
paths:
  /alerts:
    post:
      description: This endpoint retrieves the alerts listing. By default, it will return open alerts. An alert is a list of new risks seen since the last alert was closed. You can paginate with a cursor using the 'id' column.
      parameters:
      - description: The field name that you want to sort by. Many fields in the response are sortable, but not all.
        in: query
        name: sortBy
        schema:
          description: The field name that you want to sort by. Many fields in the response are sortable, but not all.
          nullable: true
          type: string
      - description: 'ASC or DESC. Defaults: DESC'
        in: query
        name: sortOrder
        schema:
          description: 'ASC or DESC. Defaults: DESC'
          example: asc
          nullable: true
          type: string
      - 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/RequestAlertsListingRequestPubliclyDocumented'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseAlertSummary'
          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 listing of Alerts
      tags:
      - 'Monitoring: Entity Management'
  /entities:
    post:
      description: Use this endpoint to browse your monitored entity population. It is filterable and shows all of your entities at a glance.
      parameters:
      - description: The field name that you want to sort by. Many fields in the response are sortable, but not all.
        in: query
        name: sortBy
        schema:
          description: The field name that you want to sort by. Many fields in the response are sortable, but not all.
          nullable: true
          type: string
      - description: 'ASC or DESC. Defaults: DESC'
        in: query
        name: sortOrder
        schema:
          description: 'ASC or DESC. Defaults: DESC'
          example: asc
          nullable: true
          type: string
      - 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestEntitiesRequestPublic'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePaginatedEntitySummaries'
          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 summaries
      tags:
      - 'Monitoring: Entity Management'
  /entities/archive:
    put:
      description: This endpoint will archive one or more entities. Archived entities will no longer be monitored and will not appear in your Monitoring population.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestArchiveEntityRequestPublic'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseStatus'
          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: Archive one or more entities
      tags:
      - 'Monitoring: Entity Management'
  /entities/by-task-id/current-state/{taskID}:
    get:
      description: This endpoint retrieves a paginated list of entities created by a bulk entity creation task. If the enqueued task is not yet finished, this endpoint will return an HTTP 425 Too Early response. The response format is not in the typical summary format, but instead, it is the full format typically available from the "Retrieve an Entity's current state" endpoint.
      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 task ID returned from the upload request
        in: path
        name: taskID
        required: true
        schema:
          description: The task ID returned from the upload request
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePaginatedFullEntities'
          description: OK
        '400':
          content:
            text/plain:
              schema:
                type: string
          description: Bad Request
        '401':
          content:
            text/plain:
              schema:
                type: string
          description: Unauthorized
        '425':
          content:
            text/plain:
              schema:
                type: string
          description: Too Early
        '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 the entities created by a bulk entity creation task
      tags:
      - 'Monitoring: Entity Management'
  /entity/{entityURN}:
    get:
      description: This endpoint includes a single entity's latest indicators, matches, and profile information.
      parameters:
      - 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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntity'
          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 an entity's current state
      tags:
      - 'Monitoring: Entity Management'
  /entity/{entityURN}/news:
    post:
      description: This endpoint will return a paginated list of machine-curated Sigma News events for a given entity.
      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 field name that you want to sort by. Many fields in the response are sortable, but not all.
        in: query
        name: sortBy
        schema:
          description: The field name that you want to sort by. Many fields in the response are sortable, but not all.
          nullable: true
          type: string
      - description: 'ASC or DESC. Defaults: DESC'
        in: query
        name: sortOrder
        schema:
          description: 'ASC or DESC. Defaults: DESC'
          example: asc
          nullable: true
          type: string
      - 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/RequestEntityNewsRequestPublic'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseNews'
          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 Sigma News Events for a given entity
      tags:
      - 'Monitoring: Entity Management'
  /entity/{entityURN}/profile-by-matches:
    post:
      description: This endpoint returns profile information (KYC and Facets), but match-by-match. This allows you to correlate profile information to matches.
      parameters:
      - 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/RequestMatchesSummaryRequestPublic'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseProfileInformationByMatch'
          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 profile information, divided by match
      tags:
      - 'Monitoring: Entity Management'
  /news/event/{uuid}/article/{hash}:
    get:
      description: This endpoint retrieves the full body of a news article referenced in a Sigma News Event. For licensing and performance reasons, this must be called only as a response to user action, and not in bulk. The response includes highlights of relevant phrases, entities, and locations in the article.
      parameters:
      - description: The individual article. Each article is uniquely identified by its hash.
        in: path
        name: hash
        required: true
        schema:
          description: The individual article. Each article is uniquely identified by its hash.
          type: string
      - description: The event UUID that includes the article. In the entity news endpoint, this is called the event's ID
        in: path
        name: uuid
        required: true
        schema:
          description: The event UUID that includes the article. In the entity news endpoint, this is called the event's ID
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigmaidEventArticle'
          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 the full body of a referenced news article
      tags:
      - 'Monitoring: Entity Management'
components:
  schemas:
    SigmaidCustomEntityField:
      properties:
        key:
          type: string
        value:
          type: string
      type: object
    SigmaidTextWithSource:
      properties:
        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
        value:
          example: <text>
          type: string
      type: object
    ResponseMatches:
      properties:
        matchesRequiringReview:
          description: Used only for user-review-enabled clients. Matches that have been escalated for review, but have not yet been reviewed.
          items:
            $ref: '#/components/schemas/ResponseMatch'
          type: array
        negativelyDecisionedMatches:
          description: Matches that a user in your organization has marked as not a valid match. These are not considered for risk, indicators, and profile data in the entity.
          items:
            $ref: '#/components/schemas/ResponseMatch'
          nullable: true
          type: array
        trueMatches:
          description: Matches that are in-force for this entity. These influence risk, indicators, and profile data.
          items:
            $ref: '#/components/schemas/ResponseMatch'
          nullable: true
          type: array
      type: object
    ResponseSearchParameters:
      properties:
        aliases:
          items:
            example: Ingen Corp.
            type: string
          nullable: true
          type: array
        countries:
          items:
            example: CR
            type: string
          nullable: true
          type: array
        dob:
          nullable: true
          type: string
        entityType:
          example: company
          type: string
      type: object
    SigmaidEconomicActivity:
      properties:
        code:
          type: string
        label:
          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
      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
    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
    ResponseAlertIndicatorSummary:
      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
        lastAddedAt:
          description: The most recent time an indicator was added to the alert.
          format: date-time
          type: string
        maxScore:
          example: 100
          type: integer
      type: object
    ResponseIndicators:
      properties:
        acceptedRisks:
          description: The risk indicators that have been accepted by a user in your organization. These are not considered for risk score calculation.
          items:
            $ref: '#/components/schemas/ResponseIndicator'
          nullable: true
          type: array
        activeRisks:
          description: The active risk indicators that are currently influencing the entity risk score.
          items:
            $ref: '#/components/schemas/ResponseIndicator'
          nullable: true
          type: array
        risksRequiringReview:
          description: Used only for user-review-enabled clients. Indicators that have been escalated for review, but have not yet been reviewed.
          items:
            $ref: '#/components/schemas/ResponseIndicator'
          type: array
      type: object
    ResponseRiskMetadata:
      properties:
        newsMetadata:
          description: The news events that are currently detected
          items:
            $ref: '#/components/schemas/ResponseNewsMetadata'
          nullable: true
          type: array
        pepLevels:
          description: The PEP levels that are currently detected
          items:
            example: PEP Level 1
            type: string
          nullable: true
          type: array
        sanctionLists:
          description: The sanction lists that are currently detected
          items:
            example: sanctions_ofac
            type: string
          nullable: true
          type: array
      type: object
    RequestAlertsListingRequestPubliclyDocumented:
      items:
        type: string
      nullable: true
      type: array
    RequestEntitiesRequestPublic:
      properties:
        filters:
          $ref: '#/components/schemas/RequestEntitiesFilterRequest'
        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
        sortBy:
          description: The field name that you want to sort by. Many fields in the response are sortable, but not all.
          nullable: true
          type: string
        sortOrder:
          description: 'ASC or DESC. Defaults: DESC'
          example: asc
          nullable: true
          type: string
        total:
          description: Total number of results. Ignored in requests, used in responses.
          example: 15000
          type: integer
      type: object
    RequestEntityNewsRequestPublic:
      properties:
        filters:
          $ref: '#/components/schemas/RequestEntityNewsFilters'
        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
        sortBy:
          description: The field name that you want to sort by. Many fields in the response are sortable, but not all.
          nullable: true
          type: string
        sortOrder:
          description: 'ASC or DESC. Defaults: DESC'
          example: asc
          nullable: true
          type: string
        total:
          description: Total number of results. Ignored in requests, used in responses.
          example: 15000
          type: integer
      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
    RequestArchiveEntityRequestPublic:
      properties:
        customerKeys:
          description: The entity customer keys to archive.
          items:
            type: string
          nullable: true
          type: array
        entityURNs:
          description: The entity URNs to archive.
          items:
            type: string
          nullable: true
          type: array
      type: object
    SigmaidPoliticalPosition:
      properties:
        country:
          type: string
        description:
          type: string
        from:
          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
        to:
          nullable: true
          type: string
      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
    ResponseEntityDispositionState:
      properties:
        dispositionSetAtTime:
          description: The time when the disposition was last set
          example: '2020-01-01T00:00:00Z'
          format: date-time
          nullable: true
          type: string
        dispositionSetByUserName:
          description: The name of the user who last set the disposition
          example: John Hammond
          nullable: true
          type: string
        dispositionSetByUserURN:
          description: The URN of the user who last set the disposition
          

# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sigma-ratings/refs/heads/main/openapi/sigma-ratings-monitoring-entity-management-api-openapi.yml