openapi: 3.0.2
info:
  description: |
    Moov Watchman offers download, parse, and search functions over numerous trade sanction lists from the United States, agencies, and nonprofits for complying with regional laws.

    > For documentation on older releases of Watchman (v0.31.x series), please visit the [older docs website](https://github.com/moov-io/watchman/tree/v0.31.3/docs) in our GitHub repository.
  contact:
    url: https://github.com/moov-io/watchman
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Watchman API
  version: v2

servers:
  - url: http://localhost:8084
    description: Local development

paths:
  /v2/listinfo:
    get:
      summary: Get information about available sanction lists
      description: Returns information about the lists watchman has prepared and indexed for search
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInfoResponse'
          description: Current lists watchman has prepared and indexed for search
          headers:
            Access-Control-Allow-Origin:
              description: '*'
              schema:
                type: string
            Content-Type:
              description: application/json
              schema:
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unexpected error
  /v2/data/refresh:
    get:
      summary: Get the status of the data refresh
      description: Returns the state, timing, and any error of the current or most recent data refresh
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshStatusResponse'
          description: Status of the current or most recent data refresh
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unexpected error
    post:
      summary: Trigger a data refresh
      description: |
        Triggers an on-demand refresh of all configured sanction lists. The refresh runs in
        the background and the call returns 202 immediately. Poll GET /v2/data/refresh to
        observe progress and completion.
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshStatusResponse'
          description: Refresh accepted and running in the background
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshStatusResponse'
          description: A refresh is already running
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unexpected error
  /v2/search:
    get:
      summary: Search for entities in sanction lists
      description: Search for entities in the sanction lists based on the provided parameters
      parameters:
        - name: name
          in: query
          description: Name of the entity to search for
          required: false
          schema:
            type: string
        - name: source
          in: query
          description: Source list to filter entity
          required: false
          schema:
            type: string
        - name: sourceID
          in: query
          description: Original list identifier
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: Type of entity to search for
          required: false
          schema:
            type: string
            enum:
              - person
              - business
              - organization
              - aircraft
              - vessel
        - name: altNames
          in: query
          description: Alternative names for the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: limit
          in: query
          description: Maximum number of results to return (default 10, max 100)
          required: false
          schema:
            type: integer
            default: 10
            maximum: 100
            minimum: 1
        - name: minMatch
          in: query
          description: Minimum match threshold for search results
          required: false
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 1
        - name: requestID
          in: query
          description: Client-provided ID for request tracking
          required: false
          schema:
            type: string
        - name: debug
          in: query
          description: Enable debug mode for additional information
          required: false
          schema:
            type: boolean
        - name: debugSourceIDs
          in: query
          description: Comma-separated list of source IDs to debug
          required: false
          schema:
            type: string
        - name: format
          in: query
          description: Output format for the search response (default watchman). May also be set via the Accept header.
          required: false
          schema:
            type: string
            enum:
              - watchman
              - senzing
              - senzing/json
              - senzing/jsonl
              - senzing/ndjson

        # Person-specific parameters
        - name: gender
          in: query
          description: Gender of the person (for type=person)
          required: false
          schema:
            type: string
        - name: birthDate
          in: query
          description: Birth date of the person (for type=person) in YYYY-MM-DD, YYYY-MM, or YYYY format
          required: false
          schema:
            type: string
        - name: deathDate
          in: query
          description: Death date of the person (for type=person) in YYYY-MM-DD, YYYY-MM, or YYYY format
          required: false
          schema:
            type: string
        - name: titles
          in: query
          description: Titles of the person (for type=person)
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true

        # Business and Organization parameters
        - name: created
          in: query
          description: Creation date of the business/organization in YYYY-MM-DD, YYYY-MM, or YYYY format
          required: false
          schema:
            type: string
        - name: dissolved
          in: query
          description: Dissolution date of the business/organization in YYYY-MM-DD, YYYY-MM, or YYYY format
          required: false
          schema:
            type: string

        # Aircraft parameters
        - name: aircraftType
          in: query
          description: Type of aircraft (for type=aircraft)
          required: false
          schema:
            type: string
        - name: icaoCode
          in: query
          description: ICAO code of the aircraft (for type=aircraft)
          required: false
          schema:
            type: string
        - name: model
          in: query
          description: Model of the aircraft (for type=aircraft) or vessel (for type=vessel)
          required: false
          schema:
            type: string
        - name: serialNumber
          in: query
          description: Serial number of the aircraft (for type=aircraft)
          required: false
          schema:
            type: string
        - name: built
          in: query
          description: Build date of the aircraft (for type=aircraft) or vessel (for type=vessel) in YYYY-MM-DD, YYYY-MM, or YYYY format
          required: false
          schema:
            type: string
        - name: flag
          in: query
          description: Flag/country of the aircraft (for type=aircraft) or vessel (for type=vessel)
          required: false
          schema:
            type: string

        # Vessel parameters
        # (also supports: flag, built, model documented above under aircraft)
        - name: imoNumber
          in: query
          description: IMO number of the vessel (for type=vessel)
          required: false
          schema:
            type: string
        - name: vesselType
          in: query
          description: Type of vessel (for type=vessel)
          required: false
          schema:
            type: string
        - name: mmsi
          in: query
          description: MMSI of the vessel (for type=vessel)
          required: false
          schema:
            type: string
        - name: callSign
          in: query
          description: Call sign of the vessel (for type=vessel)
          required: false
          schema:
            type: string
        - name: owner
          in: query
          description: Owner of the vessel (for type=vessel)
          required: false
          schema:
            type: string
        - name: tonnage
          in: query
          description: Tonnage of the vessel (for type=vessel)
          required: false
          schema:
            type: integer
        - name: grossRegisteredTonnage
          in: query
          description: Gross registered tonnage of the vessel (for type=vessel)
          required: false
          schema:
            type: integer

        # Contact parameters
        - name: email
          in: query
          description: Email address of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: emailAddress
          in: query
          description: Alternative parameter for email address of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: emailAddresses
          in: query
          description: Alternative parameter for email addresses of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: phone
          in: query
          description: Phone number of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: phoneNumber
          in: query
          description: Alternative parameter for phone number of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: phoneNumbers
          in: query
          description: Alternative parameter for phone numbers of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: fax
          in: query
          description: Fax number of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: faxNumber
          in: query
          description: Alternative parameter for fax number of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: faxNumbers
          in: query
          description: Alternative parameter for fax numbers of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: website
          in: query
          description: Website of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: websites
          in: query
          description: Alternative parameter for websites of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true

        # Address parameters
        - name: address
          in: query
          description: Address of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: addresses
          in: query
          description: Alternative parameter for addresses of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true

        # Crypto address parameters
        - name: cryptoAddress
          in: query
          description: Cryptocurrency address of the entity in format CURRENCY:ADDRESS (e.g., XBT:x123456)
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
        - name: cryptoAddresses
          in: query
          description: Alternative parameter for cryptocurrency addresses of the entity
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true

        # Government identifier parameters. Value format is `country:identifier` (e.g., `gov_passport=US:123456789`).
        - name: gov_passport
          in: query
          description: Passport identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_drivers-license
          in: query
          description: Driver's license identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_national-id
          in: query
          description: National ID in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_tax-id
          in: query
          description: Tax ID in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_ssn
          in: query
          description: Social Security Number in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_cedula
          in: query
          description: Cedula identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_curp
          in: query
          description: CURP identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_cuit
          in: query
          description: CUIT identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_electoral
          in: query
          description: Electoral identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_business-registration
          in: query
          description: Business registration number in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_commercial-registry
          in: query
          description: Commercial registry number in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_birth-certificate
          in: query
          description: Birth certificate number in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_refugee-id
          in: query
          description: Refugee ID in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_diplomatic-passport
          in: query
          description: Diplomatic passport identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_personal-id
          in: query
          description: Personal ID in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_citizenship
          in: query
          description: Citizenship identifier in `country:identifier` format
          required: false
          schema:
            type: string
        - name: gov_nationality
          in: query
          description: Nationality identifier in `country:identifier` format
          required: false
          schema:
            type: string

      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
            application/x-ndjson:
              schema:
                type: string
                description: Senzing-formatted body (NDJSON/JSONL for format=senzing/jsonl or senzing/ndjson, JSON array otherwise)
          description: Successful search
          headers:
            Access-Control-Allow-Origin:
              description: '*'
              schema:
                type: string
            Content-Type:
              description: application/json or application/x-ndjson
              schema:
                type: string
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
          headers:
            Content-Type:
              description: application/json
              schema:
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unexpected error

  /v2/ingest/{fileType}:
    post:
      summary: Import a file as a dataset
      description: Import a file as an in-memory dataset for use in searches.
      parameters:
        - name: fileType
          in: path
          description: Dataset name which matches a schema defined in the Watchman config
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              description: A plaintext CSV file
              type: string
              example: |
                first,middle,last
                john,,doe
      responses:
        '200':
          description: File ingested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestFileResponse'
        '400':
          description: Missing or invalid fileType
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v2/export/{fileType}:
    get:
      summary: Export an ingested dataset
      description: Export the entities of an ingested dataset in the chosen format.
      parameters:
        - name: fileType
          in: path
          description: Dataset name which matches a schema defined in the Watchman config
          required: true
          schema:
            type: string
        - name: format
          in: query
          description: Output format for the export (default watchman). May also be set via the Accept header.
          required: false
          schema:
            type: string
            enum:
              - watchman
              - senzing
              - senzing/json
              - senzing/jsonl
              - senzing/ndjson
      responses:
        '200':
          description: Export successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entity'
            application/x-ndjson:
              schema:
                type: string
                description: Senzing-formatted body (NDJSON/JSONL for format=senzing/jsonl or senzing/ndjson, JSON array otherwise)
          headers:
            Access-Control-Allow-Origin:
              description: '*'
              schema:
                type: string
            Content-Type:
              description: application/json or application/x-ndjson
              schema:
                type: string
        '400':
          description: Missing or invalid fileType
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    Address:
      properties:
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: Second line of the address
        city:
          type: string
          description: City name
        postalCode:
          type: string
          description: Postal or ZIP code
        state:
          type: string
          description: State, province, or region
        country:
          type: string
          description: ISO-3166 country code
        latitude:
          type: number
          format: double
          description: Latitude of the address
        longitude:
          type: number
          format: double
          description: Longitude of the address
      type: object
    Affiliation:
      properties:
        entityName:
          type: string
          description: Name of the related entity
        type:
          type: string
          description: Relationship to the related entity (e.g., "Linked To", "Subsidiary Of", "Owned By")
        details:
          type: string
          description: Additional details about the relationship
      type: object
    Aircraft:
      properties:
        altNames:
          items:
            type: string
          type: array
          description: Alternative names for the aircraft
        built:
          format: date-time
          type: string
          description: Build date of the aircraft
        flag:
          type: string
          description: Country flag of the aircraft (ISO-3166)
        icaoCode:
          type: string
          description: ICAO code of the aircraft
        model:
          type: string
          description: Model of the aircraft
        name:
          type: string
          description: Name of the aircraft
        serialNumber:
          type: string
          description: Serial number of the aircraft
        type:
          type: string
          description: Type of aircraft
      type: object
    Business:
      properties:
        altNames:
          items:
            type: string
          type: array
          description: Alternative names for the business
        created:
          format: date-time
          type: string
          description: Creation date of the business
        dissolved:
          format: date-time
          type: string
          description: Dissolution date of the business
        governmentIDs:
          items:
            $ref: '#/components/schemas/GovernmentID'
          type: array
          description: Government-issued identifiers for the business
        name:
          type: string
          description: Name of the business
      type: object
    Contact:
      properties:
        emailAddresses:
          items:
            type: string
          type: array
          description: Email addresses associated with the entity
        faxNumbers:
          items:
            type: string
          type: array
          description: Fax numbers associated with the entity
        phoneNumbers:
          items:
            type: string
          type: array
          description: Phone numbers associated with the entity
        websites:
          items:
            type: string
          type: array
          description: Websites associated with the entity
      type: object
    CryptoAddress:
      properties:
        address:
          type: string
          description: Cryptocurrency address
        currency:
          type: string
          description: Cryptocurrency code (e.g., BTC, ETH, XBT)
      type: object
    Entity:
      properties:
        addresses:
          items:
            $ref: '#/components/schemas/Address'
          type: array
          description: Addresses associated with the entity
        affiliations:
          items:
            $ref: '#/components/schemas/Affiliation'
          type: array
          description: Other entities this entity is connected to
        aircraft:
          $ref: '#/components/schemas/Aircraft'
          description: Aircraft details (if entity type is aircraft)
        business:
          $ref: '#/components/schemas/Business'
          description: Business details (if entity type is business)
        contact:
          $ref: '#/components/schemas/Contact'
          description: Contact information for the entity
        cryptoAddresses:
          items:
            $ref: '#/components/schemas/CryptoAddress'
          type: array
          description: Cryptocurrency addresses associated with the entity
        entityType:
          enum:
          - unknown
          - person
          - business
          - organization
          - aircraft
          - vessel
          type: string
          description: Type of entity
        historicalInfo:
          items:
            $ref: '#/components/schemas/HistoricalInfo'
          type: array
          description: Historical values for fields that have since changed
        name:
          type: string
          description: Primary name of the entity
        organization:
          $ref: '#/components/schemas/Organization'
          description: Organization details (if entity type is organization)
        person:
          $ref: '#/components/schemas/Person'
          description: Person details (if entity type is person)
        sanctionsInfo:
          $ref: '#/components/schemas/SanctionsInfo'
          description: Sanctions programs and details for the entity
        sourceList:
          type: string
          description: Original list the entity is from
        sourceID:
          type: string
          description: Original list identifier
        sourceData:
          type: object
          description: Original source data
        vessel:
          $ref: '#/components/schemas/Vessel'
          description: Vessel details (if entity type is vessel)
      type: object
    ErrorResponse:
      properties:
        error:
          type: string
          description: Error message
      type: object
    GovernmentID:
      properties:
        name:
          type: string
          description: Display name for this identifier
        type:
          enum:
          - passport
          - drivers-license
          - national-id
          - tax-id
          - ssn
          - cedula
          - curp
          - cuit
          - electoral
          - business-registration
          - commercial-registry
          - birth-certificate
          - refugee-id
          - diplomatic-passport
          - personal-id
          - citizenship
          - nationality
          type: string
          description: Kind of government ID
        country:
          type: string
          description: Issuing country (ISO-3166)
        identifier:
          type: string
          description: The identifier value
      type: object
    HistoricalInfo:
      properties:
        type:
          type: string
          description: Kind of historical value (e.g., "Former Name", "Previous Flag")
        value:
          type: string
          description: The historical value itself
        date:
          format: date-time
          type: string
          description: When this value applied
      type: object
    ListInfoResponse:
      properties:
        lists:
          type: object
          example:
            us_csl: 442
            us_ofac: 17646
          description: Count of entities parsed from each list
        listHashes:
          type: object
          example:
            us_csl: "a572...cf42"
            us_ofac: "0629...9aab"
          description: Hash of each list's original contents
        startedAt:
          format: date-time
          type: string
          description: Timestamp of when list refresh started
        endedAt:
          format: date-time
          type: string
          description: Timestamp of when list refresh completed
        version:
          type: string
          example: "v0.51.0"
          description: Version of the Watchman service
      type: object
    RefreshStatusResponse:
      properties:
        state:
          type: string
          enum:
            - idle
            - running
            - succeeded
            - failed
          example: succeeded
          description: Lifecycle state of the current or most recent refresh
        trigger:
          type: string
          enum:
            - startup
            - scheduled
            - manual
          description: What initiated the refresh
        startedAt:
          format: date-time
          type: string
          description: Timestamp of when the refresh started
        finishedAt:
          format: date-time
          type: string
          description: Timestamp of when the refresh completed (absent while running)
        duration:
          type: string
          example: "2m3s"
          description: Wall-clock duration of the last completed refresh
        lastError:
          type: string
          description: Error message from the most recent failed refresh, if any
      type: object
    Organization:
      properties:
        altNames:
          items:
            type: string
          type: array
          description: Alternative names for the organization
        created:
          format: date-time
          type: string
          description: Creation date of the organization
        dissolved:
          format: date-time
          type: string
          description: Dissolution date of the organization
        governmentIDs:
          items:
            $ref: '#/components/schemas/GovernmentID'
          type: array
          description: Government-issued identifiers for the organization
        name:
          type: string
          description: Name of the organization
      type: object
    Person:
      properties:
        altNames:
          items:
            type: string
          type: array
          description: Alternative names for the person
        birthDate:
          format: date-time
          type: string
          description: Birth date of the person
        deathDate:
          format: date-time
          type: string
          description: Death date of the person
        gender:
          type: string
          description: Gender of the person
        governmentIDs:
          items:
            $ref: '#/components/schemas/GovernmentID'
          type: array
          description: Government-issued identifiers for the person
        name:
          type: string
          description: Name of the person
        placeOfBirth:
          type: string
          description: Place of birth of the person
        titles:
          items:
            type: string
          type: array
          description: Titles held by the person
      type: object
    SanctionsInfo:
      properties:
        programs:
          items:
            type: string
          type: array
          description: Sanction programs the entity falls under (e.g., "SDGT", "IRGC")
        secondary:
          type: boolean
          description: Whether the entity is subject to secondary sanctions
        description:
          type: string
          description: Additional sanctions details
      type: object
    ScorePiece:
      properties:
        score:
          type: number
          format: float
          description: Score for this piece (0-1)
        weight:
          type: number
          format: float
          description: Weight applied to this piece in the final score
        matched:
          type: boolean
          description: Whether this piece matched
        required:
          type: boolean
          description: Whether this piece is required for a high overall score
        exact:
          type: boolean
          description: Whether this piece was an exact match
        fieldsCompared:
          type: integer
          description: Number of fields that were compared
        pieceType:
          type: string
          description: Type of comparison this piece represents (e.g., "identifiers", "name")
      type: object
    SearchedEntity:
      description: An Entity returned from a search, with match score and optional scoring details
      allOf:
        - $ref: '#/components/schemas/Entity'
        - type: object
          properties:
            match:
              type: number
              format: float
              minimum: 0
              maximum: 1
              description: Match score for this entity against the query
            debug:
              type: string
              description: Base64-encoded field-level match details (only set when ?debug=true)
            details:
              $ref: '#/components/schemas/SimilarityScore'
              description: Field-level scoring breakdown
    SearchResponse:
      properties:
        query:
          $ref: '#/components/schemas/Entity'
        entities:
          items:
            $ref: '#/components/schemas/SearchedEntity'
          type: array
          description: List of matching entities
      type: object
    SimilarityScore:
      properties:
        pieces:
          items:
            $ref: '#/components/schemas/ScorePiece'
          type: array
          description: Per-comparison score breakdown
        finalScore:
          type: number
          format: float
          description: Computed final match score
      type: object
    Vessel:
      properties:
        altNames:
          items:
            type: string
          type: array
          description: Alternative names for the vessel
        built:
          format: date-time
          type: string
          description: Build date of the vessel
        callSign:
          type: string
          description: Call sign of the vessel
        flag:
          type: string
          description: Country flag of the vessel (ISO-3166)
        grossRegisteredTonnage:
          type: integer
          description: Gross registered tonnage of the vessel
        imoNumber:
          type: string
          description: IMO number of the vessel
        mmsi:
          type: string
          description: MMSI of the vessel
        model:
          type: string
          description: Model of the vessel
        name:
          type: string
          description: Name of the vessel
        owner:
          type: string
          description: Owner of the vessel
        tonnage:
          type: integer
          description: Tonnage of the vessel
        type:
          type: string
          description: Type of vessel
      type: object
    IngestFileResponse:
      properties:
        fileType:
          type: string
          description: Dataset name used for file import
        entities:
          items:
            $ref: '#/components/schemas/Entity'
          type: array
          description: Entities that were imported