Sigma360 Monitoring: Entity Management API

openapi: 3.1.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 Account 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:
    ResponseNewsMetadata:
      properties:
        count:
          description: The number of news events for this type that are currently detected
          example: 3
          type: integer
        eventNewsType:
          description: The event news type currently detected
          example: Legal Risk
          type: string
        samplePublishers:
          description: A sample of the publishers that are currently detected
          items:
            example: The New York Times
            type: string
          nullable: true
          type: array
        unformattedEventNewsType:
          description: The unformatted event news type currently detected
          example: legal_risk
          type: string
      type: object
    ResponseProfileInformationByMatch:
      properties:
        aliases:
          items:
            type: string
          type: array
        aliasesWithSources:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          type: array
        corporateNumbers:
          items:
            $ref: '#/components/schemas/SigmaidCorporateNumber'
          nullable: true
          type: array
        dobs:
          items:
            $ref: '#/components/schemas/SigmaidDateWithSource'
          nullable: true
          type: array
        economicActivities:
          additionalProperties:
            items:
              $ref: '#/components/schemas/SigmaidEconomicActivity'
            type: array
          nullable: true
          type: object
        facetType:
          type: string
        facts:
          items:
            $ref: '#/components/schemas/SigmaidFact'
          type: array
        foundedDates:
          items:
            $ref: '#/components/schemas/SigmaidDateWithSource'
          nullable: true
          type: array
        genders:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        identifications:
          items:
            $ref: '#/components/schemas/SigmaidIdentification'
          nullable: true
          type: array
        imo:
          $ref: '#/components/schemas/SigmaidTextWithSource'
        incorporationTypes:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        linesOfBusiness:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        locations:
          items:
            $ref: '#/components/schemas/SigmaidLocation'
          type: array
        manufactureDates:
          items:
            $ref: '#/components/schemas/SigmaidDateWithSource'
          nullable: true
          type: array
        maritimeCallSigns:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        models:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        nationalities:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        operators:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        otherIdentifiers:
          items:
            $ref: '#/components/schemas/SigmaidIdentification'
          nullable: true
          type: array
        politicalPositions:
          items:
            $ref: '#/components/schemas/SigmaidPoliticalPosition'
          nullable: true
          type: array
        portsOfRegistry:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        serialNumbers:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        sigmaID:
          type: string
        statuses:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        tailNumbers:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
        types:
          items:
            $ref: '#/components/schemas/SigmaidTextWithSource'
          nullable: true
          type: array
      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
    ResponseMatchSummary:
      properties:
        highestEntityRisk:
          type: string
        matchName:
          type: string
        numEvents:
          type: integer
        yearOfBirth:
          nullable: true
          type: integer
      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
    ResponsePaginatedEntitySummaries:
      properties:
        entities:
          items:
            $ref: '#/components/schemas/ResponseEntitySummary'
          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
    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
    ResponseIndicator:
      properties:
        category:
          example: Sanctions
          type: string
        causalSigmaID:
          $ref: '#/components/schemas/SigmaidSummarySearchResultRow'
        code:
          example: SAN006
          type: string
        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
        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
    RequestEntityNewsFilters:
      properties:
        endTime:
          type: string
        eventEntityRisks:
          items:
            type: string
          nullable: true
          type: array
        eventType:
          type: string
        eventTypes:
          items:
            type: string
          nullable: true
          type: array
        isDecisionedAgainst:
          description: Only return news that has been marked accepted or decisioned against.
          type: boolean
        languages:
          items:
            type: string
          nullable: true
          type: array
        matchIDs:
          description: An array of match IDs to include news from.
          items:
            type: string
          nullable: true
          type: array
        matchNames:
          items:
            type: string
          nullable: true
          type: array
        minMaterialityScore:
          type: number
        onlyReviewRequiredNews:
          description: Only return news that requires review. Causes isDecisionedAgainst to be ignored
          typ

# --- 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