Politically Exposed Persons (PEP) Screening by Name

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Full name of person to screen"
    },
    "country": {
      "type": "string",
      "description": "ISO country code filter (optional)"
    },
    "birth_date": {
      "type": "string",
      "description": "Alias for date_of_birth (optional)"
    },
    "date_of_birth": {
      "type": "string",
      "description": "ISO date of birth (YYYY-MM-DD) for disambiguation, reduces false positives on common names (optional)"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "query",
    "country_filter",
    "birth_date_filter",
    "is_pep",
    "match_count",
    "total_results",
    "matches",
    "source",
    "screened_at",
    "lists_queried"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "The name text exactly as submitted, echoed back."
    },
    "is_pep": {
      "type": "boolean",
      "description": "Whether any match was found, e.g. true for a head of state, false for an obscure individual."
    },
    "source": {
      "type": "string",
      "description": "The underlying watchlist data source, e.g. 'dilisense'."
    },
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The matched entity's name from the watchlist -- not always identical to the query text (a fuzzy/close-name match, e.g. 'Vladimir Putin Jr.' or an unrelated similarly-spelled name, was observed alongside an exact match)."
          },
          "datasets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Source dataset code(s) the match came from, e.g. 'dilisense_pep'."
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO country codes, e.g. ['RU']."
          },
          "positions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Public offices/roles held, often with date ranges (e.g. '2000-05-07 - 2008-05-07 President of Russia'). Observed empty on a relatives/close-associates match and populated with up to 26 entries on a long-serving politician's match."
          },
          "classification": {
            "type": "string",
            "description": "e.g. 'POLITICIAN', 'RELATIVES_AND_CLOSE_ASSOCIATES'."
          },
          "last_updated_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Observed as null on every match in testing."
          }
        },
        "additionalProperties": true
      },
      "description": "Empty array observed when `is_pep` is false."
    },
    "match_count": {
      "type": "number",
      "description": "Number of matches returned, e.g. 3 or 0."
    },
    "screened_at": {
      "type": "string",
      "description": "ISO 8601 timestamp of when the screening ran."
    },
    "lists_queried": {
      "type": "object",
      "properties": {
        "collection": {
          "type": "string",
          "description": "e.g. 'dilisense/consolidated-pep'."
        },
        "major_lists": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source_count": {
          "type": "number",
          "description": "Number of source lists aggregated, e.g. 230."
        },
        "freshness_note": {
          "type": "string"
        }
      },
      "description": "Metadata about the watchlist collection queried, not specific to this query's result.",
      "additionalProperties": true
    },
    "total_results": {
      "type": "number",
      "description": "Total matching records, e.g. 3 for a head of state or 0 when nothing matches."
    },
    "country_filter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Echoes the `country` input filter if supplied; null when no country filter is given."
    },
    "birth_date_filter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Echoes the `date_of_birth`/`birth_date` input filter if supplied; null when no birth-date filter is given."
    }
  },
  "description": "The PEP screening result.",
  "additionalProperties": true
}