openapi: 3.0.3
info:
  title: Socure Global Watchlist Monitoring API
  version: '3.0'
  description: |
    Continuous monitoring of customer identities against global sanctions lists
    (OFAC, UN, EU, HMT, DFAT), PEP lists, and adverse media sources. Submit profiles
    for monitoring, retrieve match alerts, manage match dispositions, and receive
    webhook callbacks when a customer matches a newly added or updated list entry.
servers:
- url: https://api.socure.com
  description: Production
- url: https://sandbox.socure.com
  description: Sandbox
security:
- SocureToken: []
tags:
- name: Monitoring
- name: Alerts
paths:
  /api/3.0/watchlist/monitoring/profiles:
    post:
      tags:
      - Monitoring
      operationId: enrollMonitoringProfile
      summary: Enroll A Monitoring Profile
      description: Enroll an identity for continuous watchlist monitoring.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitoringEnrollment'
      responses:
        '200':
          description: Profile enrolled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringProfile'
  /api/3.0/watchlist/monitoring/profiles/{profileId}:
    parameters:
    - name: profileId
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Monitoring
      operationId: getMonitoringProfile
      summary: Get A Monitoring Profile
      responses:
        '200':
          description: Monitoring profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringProfile'
    delete:
      tags:
      - Monitoring
      operationId: removeMonitoringProfile
      summary: Remove A Monitoring Profile
      responses:
        '204':
          description: Profile removed.
  /api/3.0/watchlist/monitoring/alerts:
    get:
      tags:
      - Alerts
      operationId: listMonitoringAlerts
      summary: List Monitoring Alerts
      parameters:
      - name: profileId
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - new
          - in_review
          - cleared
          - confirmed
      responses:
        '200':
          description: Alert list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitoringAlert'
  /api/3.0/watchlist/monitoring/alerts/{alertId}:
    parameters:
    - name: alertId
      in: path
      required: true
      schema:
        type: string
    patch:
      tags:
      - Alerts
      operationId: updateMonitoringAlert
      summary: Update A Monitoring Alert Disposition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - new
                  - in_review
                  - cleared
                  - confirmed
                notes:
                  type: string
      responses:
        '200':
          description: Alert updated.
components:
  securitySchemes:
    SocureToken:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    MonitoringEnrollment:
      type: object
      required:
      - referenceId
      properties:
        referenceId:
          type: string
          description: ID+ referenceId from the original watchlist evaluation.
        customerUserId:
          type: string
        webhookUrl:
          type: string
          format: uri
    MonitoringProfile:
      type: object
      properties:
        profileId:
          type: string
        customerUserId:
          type: string
        enrolledAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - active
          - removed
    MonitoringAlert:
      type: object
      properties:
        alertId:
          type: string
        profileId:
          type: string
        sourceListName:
          type: string
        matchDetails:
          type: object
          additionalProperties: true
        status:
          type: string
        createdAt:
          type: string
          format: date-time