Interpreting AML Screening Results

How to Read an AML Result

When you execute a workflow containing an AML step, the API response provides a rich set of data to help you understand the outcome. This guide provides a structured, “top-down” walkthrough of how to parse the workflowResult object.

View Full API Response Example

The examples in this guide refer to a workflow execution response where Adverse Media matches were found. Click to expand and see the full structure.

{
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
  "workflowResult": {
    "workflowExecutionId": "01K55F466SQBT41KMQ7PWGEEN3",
    "workflowExecutionState": "COMPLETED",
    "status": "REVIEW",
    "result": "REVIEW",
    "riskAssessment": {
        "riskLevel": "HIGH",
        "riskScore": 100,
        "riskFactors": [
            {
              "createdAt": "2025-09-15T01:16:45.849033Z",
              "description": "Has adverse media hits",
              "factor": "has_adverse_media",
              "riskFactorId": "b26d1a21-57f9-46ed-afc9-f7025980ad9c",
              "score": 10,
              "status": "VALID",
              "updatedAt": "2025-09-15T01:16:45.849033Z",
              "updatedRequestId": "01HN9XHZN6MGXM9JXG50K59Q85"
            }
        ]
    },
    "issues": [
      {
        "category": "AML",
        "createdAt": "2025-09-15T01:16:45.949556Z",
        "issue": "MEDIA",
        "issueId": "9e3b73c3-5050-4f42-bc4b-aa6c05a711b8",
        "severity": "WARNING",
        "workflowExecutionId": "01K55F466SQBT41KMQ7PWGEEN3"
      }
    ],
    "workflowStepResults": [
      {
        "stepName": "AML",
        "result": "HIT",
        "summary": {
          "numUnresolvedAdverseMedia": 2,
          "numUnresolvedPEP": 0,
          "numUnresolvedSanction": 0,
          "numUnresolvedWatchlist": 0,
          "providerSummaries": [
              ...
          ],
          "stepName": "AML",
          "totalFalsePositives": 0,
          "totalHits": 2,
          "totalTruePositives": 0,
          "totalUnknown": 0,
          "totalUnresolved": 2
        },
        "processResults": [
          { 
            "processResultId": "pro_01J...",
            "result": "HIT",
            "class": "AML",
            "supplementaryData": {
              "type": "AML",
              "matchData": { "name": "Test Org" },
              "mediaData": [
                {
                  "additionalData": [
                    {
                      "key": "aml.case_id",
                      "value": "..."
                    },
                    {
                      "key": "aml.search_entity_id",
                      "value": "..."
                    }
                  ],
                  "isCurrent": true,
                  "snippet": "...",
                  "source": "...",
                  "sourceDate": "...",
                  "title": "...",
                  "url": "..."
                }
              ],
              "manualStatus": "UNRESOLVED"
            }
          }
        ]
      }
    ]
  }
}

Part 1: The Overall Outcome (Final Verdict)

Always start by checking the top-level fields of the workflowResult object. These give you the final, authoritative outcome.

Field	Importance	Description
`status`	‼️	The conclusive recommendation (e.g., `PASS`, `FAIL`, `REVIEW`). Base your primary business logic on this value.
`workflowExecutionState`	‼️	Confirms the workflow’s technical status. Must be `COMPLETED`.
`issues`	⚠️	An array of problems that require manual review. If `status` is `REVIEW`, this array contains the specific reasons why.
`riskAssessment`	⚠️	The final risk profile of the entity, including the `riskLevel` and `riskScore`.

In the example, the status is REVIEW, which is directly caused by the issues array containing a MEDIA issue.

Understanding AML Issues

When the AML step finds a potential match, it generates an issue object. This is what typically drives the overall workflow status to REVIEW.

Category	Issue	Severity	Trigger Condition
`AML`	`PEP`	`WARNING`	At least one valid Process Result contains `pepData`.
`AML`	`SANCTIONS`	`WARNING`	At least one valid Process Result contains `sanctionData`.
`AML`	`MEDIA`	`WARNING`	At least one valid Process Result contains `mediaData`.
`AML`	`WATCHLIST`	`WARNING`	At least one valid Process Result contains `watchlistData`.

Part 2: The AML Step Result (`workflowStepResults`)

Next, drill down into the workflowStepResults array and find the object where stepName is AML. This object contains the specific results of the screening.

Key Field	Description
`result`	The most important field for the step. A `result` of `HIT` means at least one potential match was found and requires review. A `result` of `CLEAR` means no matches were found.
`summary`	An aggregated summary of the screening results, broken down by match type.
`processResults`	An array containing the detailed evidence for each individual watchlist match.

The AML Summary Object

The summary object gives you a quick, quantitative overview of the screening results.

"summary": {
  "numUnresolvedAdverseMedia": 2,
  "numUnresolvedPEP": 0,
  "numUnresolvedSanction": 0,
  "numUnresolvedWatchlist": 0,
  "providerSummaries": [
      {
          ...
      }
  ],
  "stepName": "AML",
  "totalFalsePositives": 0,
  "totalHits": 2,
  "totalTruePositives": 0,
  "totalUnknown": 0,
  "totalUnresolved": 2
  }

This summary immediately tells you the scale and severity of the results. For example, numUnresolvedSanction highlights if a high-risk sanctions match is present and needs immediate attention.

Part 3: The Process Results (The Raw Evidence)

When an AML step returns a HIT, the processResults array will contain one or more Process Result Objects (PROs), each with class: "AML". Each PRO represents a single potential match from a watchlist and contains all the data you need for your investigation.

Anatomy of an AML PRO

The most critical part of an AML PRO is the supplementaryData object. This is where you will find the details of the matched entity.

`supplementaryData` Field	Description
`matchData`	Core information about the matched profile (name, date of birth, countries of association).
`pepData`	If the match is a Politically Exposed Person, this array contains details about their position, level, and country.
`sanctionData`	If the match is on a Sanctions list, this array contains details about the sanction, its source, and the reason.
`watchlistData`	This array contains details for matches on other regulatory or law enforcement watchlists.
`mediaData`	If the match is from Adverse Media, this array provides snippets and links to relevant news articles.
`referenceDocs`	An array of URLs to source documents for further evidence.

Example: A Adverse Media Match PRO

This example shows a processResult for a HIT where the organization has adverse media hits. The mediaData array is populated with the specific details of the adverse media matches.

{ 
  "processResultId": "pro_01J...",
  "result": "HIT",
  "class": "AML",
  "supplementaryData": {
    "type": "AML",
    "matchData": { "name": "Test Org" },
    "mediaData": [
      {
        "additionalData": [
          {
            "key": "aml.case_id",
            "value": "..."
          },
          {
            "key": "aml.search_entity_id",
            "value": "..."
          }
        ],
        "isCurrent": true,
        "snippet": "...",
        "source": "...",
        "sourceDate": "...",
        "title": "...",
        "url": "..."
      }
    ],
    "manualStatus": "UNRESOLVED"
  }
}

Part 4: Next Steps - Classifying Hits and Re-evaluating

After your compliance team reviews the evidence in the processResults, they must classify each hit (e.g., as a FALSE_POSITIVE). This is done by updating the manualStatus of each PRO.

For a detailed guide on how to perform this action via the API, please see our AML Screening & Monitoring Documentation.

Updating the Workflow Result

Once all hits have been classified, the workflow needs to be reevaluated so the entity’s risk and workflow status reflect the classifications. This is critical for two reasons:

To Update the status: The overall workflowResult.status will only change from REVIEW to PASS or CLEAR after the workflow is re-evaluated or re-run and the AML step confirms that no unresolved hits remain.
To Clear issues: The AML step will reassess the issues. If all PROs that previously caused a MEDIA issue are now classified as FALSE_POSITIVE, the issue will be cleared from the workflow result.

There are two ways to trigger this update:

Re-evaluate the Workflow

Call the evaluate endpoint. This re-runs the decision and risk assessment steps using existing check results, without triggering new calls to external providers. This ensures the entity’s risk and workflow status are updated and the audit trail is accurate.

POST /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/evaluate

Re-run the Workflow

Call the execute endpoint to re-run the full workflow. Unless existing results are within the aging window, this will contact external providers again (e.g., run a new AML search), which incurs additional cost and resets the aging window.

POST /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute

Use /evaluate when only the decision needs updating based on changed classifications — it is faster, cheaper, and does not call external providers. It re-assesses risk using the entity’s existing check results, but does not refresh them. Use /execute when the entity’s underlying data has changed, or when you need fresh provider results because existing checks have expired beyond the aging window.

Error Handling

Scenario	Response	Recommended Action
No prior workflow execution exists	`400` - “No prior workflow execution found”	Call `/execute` first to run the initial workflow
Entity state is `DUPLICATE`	`400`	Call evaluate on the surviving entity, not the duplicate
Entity state is `BLOCKLISTED`	`403`	Resolve the blocklist status first

​How to Read an AML Result

​Part 1: The Overall Outcome (Final Verdict)

​Understanding AML Issues

​Part 2: The AML Step Result (workflowStepResults)

​The AML Summary Object

​Part 3: The Process Results (The Raw Evidence)

​Anatomy of an AML PRO

​Part 4: Next Steps - Classifying Hits and Re-evaluating

​Updating the Workflow Result

​Re-evaluate the Workflow

​Re-run the Workflow

​Error Handling

How to Read an AML Result

Part 1: The Overall Outcome (Final Verdict)

Understanding AML Issues

Part 2: The AML Step Result (`workflowStepResults`)

The AML Summary Object

Part 3: The Process Results (The Raw Evidence)

Anatomy of an AML PRO

Part 4: Next Steps - Classifying Hits and Re-evaluating

Updating the Workflow Result

Re-evaluate the Workflow

Re-run the Workflow

Error Handling