---
updatedAt: 2026-08-04T08:42:50.000Z
agentTools:
  projectIndex: https://docs.mesh.complyadvantage.com/llms.txt
---

# Retrieve risks for a transaction

Retrieve all payment-screening risks attached to a single transaction. The transaction is addressed by exactly one of two mutually exclusive query parameters: `transaction_identifier` (the internal ComplyAdvantage payment identifier, a UUID) or `transaction_external_identifier` (the client's own external payment reference, an arbitrary string). Supplying both, or neither, is a 400. Returns a 200 with an empty `risks` array when the transaction exists but produced no risks. Results are ordered by `created_at` ascending; ties are broken by risk `identifier`.


You need "Access to base payment screening functionality" enabled to use this endpoint.

# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "ps_Associate": {
        "description": "Associated party linked to the matched profile.",
        "properties": {
          "association": {
            "description": "Relationship of the associated party to the profile.",
            "type": "string"
          },
          "name": {
            "description": "Name of the associated party.",
            "type": "string"
          }
        },
        "required": [
          "association",
          "name"
        ],
        "type": "object"
      },
      "ps_AttributeValue": {
        "description": "Single structured attribute value derived from a provider field.",
        "properties": {
          "source": {
            "description": "Source associated with the attribute value, when available.",
            "nullable": true,
            "type": "string"
          },
          "value": {
            "description": "Raw attribute value returned by the provider.",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "ps_BicMatch": {
        "description": "Detailed BIC match information returned by the provider.",
        "properties": {
          "characters_matched": {
            "description": "Number of characters matched within the BIC.",
            "format": "int32",
            "type": "integer"
          },
          "match_type": {
            "description": "Type of BIC match reported by the provider.",
            "type": "string"
          },
          "matching_bic": {
            "description": "BIC value that matched the screened input.",
            "type": "string"
          }
        },
        "required": [
          "characters_matched",
          "match_type",
          "matching_bic"
        ],
        "type": "object"
      },
      "ps_Match": {
        "description": "Transparency information about the provider match.",
        "properties": {
          "details": {
            "default": null,
            "description": "Structured match details returned for name and BIC matches.",
            "items": {
              "$ref": "#/components/schemas/ps_MatchDetail"
            },
            "nullable": true,
            "type": "array"
          },
          "match_types": {
            "default": null,
            "description": "Name-based match types returned by the provider.",
            "items": {
              "description": "Name-based match types returned by the provider.",
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "score": {
            "description": "Provider score for the match, when available.",
            "format": "double",
            "nullable": true,
            "type": "number"
          },
          "text_match_terms": {
            "default": null,
            "description": "Normalised text match terms returned for text screening risks.",
            "items": {
              "$ref": "#/components/schemas/ps_TextMatchTerm"
            },
            "nullable": true,
            "type": "array"
          }
        },
        "type": "object"
      },
      "ps_MatchDetail": {
        "description": "Detailed match explanation for a single provider hit.",
        "properties": {
          "aml_types": {
            "default": null,
            "description": "AML types associated with the match detail, when available.",
            "items": {
              "description": "AML type assigned by the screening provider.",
              "enum": [
                "SANCTION",
                "WARNING",
                "FITNESS_PROBITY",
                "PEP",
                "PEP_CLASS_1",
                "PEP_CLASS_2",
                "PEP_CLASS_3",
                "PEP_CLASS_4",
                "ADVERSE_MEDIA",
                "ADVERSE_MEDIA_FINANCIAL_CRIME",
                "ADVERSE_MEDIA_VIOLENT_CRIME",
                "ADVERSE_MEDIA_SEXUAL_CRIME",
                "ADVERSE_MEDIA_TERRORISM",
                "ADVERSE_MEDIA_FRAUD",
                "ADVERSE_MEDIA_NARCOTICS",
                "ADVERSE_MEDIA_GENERAL",
                "UNKNOWN"
              ],
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "bic_matches": {
            "default": null,
            "description": "BIC match explanations, when available.",
            "items": {
              "$ref": "#/components/schemas/ps_BicMatch"
            },
            "nullable": true,
            "type": "array"
          },
          "matching_name": {
            "description": "Matching name returned for name screening hits, when available.",
            "nullable": true,
            "type": "string"
          },
          "name_matches": {
            "default": null,
            "description": "Primary name match terms, when available.",
            "items": {
              "$ref": "#/components/schemas/ps_MatchTerm"
            },
            "nullable": true,
            "type": "array"
          },
          "secondary_matches": {
            "default": null,
            "description": "Secondary name match terms, when available.",
            "items": {
              "$ref": "#/components/schemas/ps_MatchTerm"
            },
            "nullable": true,
            "type": "array"
          },
          "source_identifiers": {
            "default": null,
            "description": "ComplyAdvantage source identifiers associated with the BIC match, when available.",
            "items": {
              "description": "ComplyAdvantage source identifiers associated with the BIC match, when available.",
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "sources": {
            "default": null,
            "description": "Display names of the sources that contributed to the match, when available.",
            "items": {
              "description": "Display names of the sources that contributed to the match, when available.",
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          }
        },
        "type": "object"
      },
      "ps_MatchTerm": {
        "description": "Matched term returned for name screening transparency.",
        "properties": {
          "match_text": {
            "description": "Text that matched the screened entity.",
            "type": "string"
          },
          "match_type": {
            "description": "Type of the match term reported by the provider.",
            "type": "string"
          }
        },
        "required": [
          "match_text",
          "match_type"
        ],
        "type": "object"
      },
      "ps_MatcherDetail": {
        "description": "Matcher-specific detail payload for a risk.",
        "properties": {
          "match": {
            "$ref": "#/components/schemas/ps_Match"
          },
          "profile": {
            "$ref": "#/components/schemas/ps_Profile"
          }
        },
        "required": [
          "match",
          "profile"
        ],
        "title": "Matcher",
        "type": "object"
      },
      "ps_ProblemDetailErrorResponse": {
        "additionalProperties": true,
        "properties": {
          "detail": {
            "nullable": true,
            "type": "string"
          },
          "identifier": {
            "format": "uuid",
            "type": "string"
          },
          "instance": {
            "format": "uri",
            "nullable": true,
            "type": "string"
          },
          "status": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "timestamp": {
            "format": "date-time",
            "type": "string"
          },
          "title": {
            "nullable": true,
            "type": "string"
          },
          "type": {
            "format": "uri",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "identifier",
          "timestamp"
        ],
        "type": "object"
      },
      "ps_Profile": {
        "description": "Matched profile returned by the screening provider.",
        "properties": {
          "aka": {
            "description": "Alternative names associated with the matched profile.",
            "items": {
              "description": "Alternative names associated with the matched profile.",
              "type": "string"
            },
            "type": "array"
          },
          "aml_types": {
            "description": "AML types assigned to the matched profile.",
            "items": {
              "description": "AML type assigned by the screening provider.",
              "enum": [
                "SANCTION",
                "WARNING",
                "FITNESS_PROBITY",
                "PEP",
                "PEP_CLASS_1",
                "PEP_CLASS_2",
                "PEP_CLASS_3",
                "PEP_CLASS_4",
                "ADVERSE_MEDIA",
                "ADVERSE_MEDIA_FINANCIAL_CRIME",
                "ADVERSE_MEDIA_VIOLENT_CRIME",
                "ADVERSE_MEDIA_SEXUAL_CRIME",
                "ADVERSE_MEDIA_TERRORISM",
                "ADVERSE_MEDIA_FRAUD",
                "ADVERSE_MEDIA_NARCOTICS",
                "ADVERSE_MEDIA_GENERAL",
                "UNKNOWN"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "associates": {
            "description": "Associated parties linked to the matched profile.",
            "items": {
              "$ref": "#/components/schemas/ps_Associate"
            },
            "type": "array"
          },
          "attributes": {
            "$ref": "#/components/schemas/ps_ProfileAttributes"
          },
          "fields": {
            "description": "Raw provider fields retained for transparency.",
            "items": {
              "$ref": "#/components/schemas/ps_ProfileField"
            },
            "type": "array"
          },
          "identifier": {
            "description": "Provider identifier of the matched profile.",
            "type": "string"
          },
          "last_updated_at": {
            "description": "UTC timestamp when the provider last updated the profile, when available.",
            "example": "2024-07-18T10:29:45.453Z",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "name": {
            "description": "Primary name of the matched profile.",
            "type": "string"
          },
          "source_notes": {
            "description": "Per-source notes for the matched profile.",
            "items": {
              "$ref": "#/components/schemas/ps_SourceNote"
            },
            "type": "array"
          },
          "sources": {
            "description": "Source slugs associated with the matched profile.",
            "items": {
              "description": "Source slugs associated with the matched profile.",
              "type": "string"
            },
            "type": "array"
          },
          "type": {
            "description": "Profile category returned by the provider.",
            "enum": [
              "PERSON",
              "ORGANISATION",
              "VESSEL",
              "AIRCRAFT",
              "REF_TEXT",
              "UNKNOWN"
            ],
            "type": "string"
          }
        },
        "required": [
          "aka",
          "aml_types",
          "associates",
          "attributes",
          "fields",
          "identifier",
          "name",
          "source_notes",
          "sources",
          "type"
        ],
        "type": "object"
      },
      "ps_ProfileAttributes": {
        "description": "Structured attributes derived from provider profile fields.",
        "properties": {
          "addresses": {
            "description": "Address values derived from provider fields.",
            "items": {
              "$ref": "#/components/schemas/ps_AttributeValue"
            },
            "type": "array"
          },
          "dates_of_birth": {
            "description": "Date-of-birth values derived from provider fields.",
            "items": {
              "$ref": "#/components/schemas/ps_AttributeValue"
            },
            "type": "array"
          },
          "genders": {
            "description": "Gender values derived from provider fields.",
            "items": {
              "$ref": "#/components/schemas/ps_AttributeValue"
            },
            "type": "array"
          },
          "nationalities": {
            "description": "Nationality values derived from provider fields.",
            "items": {
              "$ref": "#/components/schemas/ps_AttributeValue"
            },
            "type": "array"
          },
          "places_of_birth": {
            "description": "Place-of-birth values derived from provider fields.",
            "items": {
              "$ref": "#/components/schemas/ps_AttributeValue"
            },
            "type": "array"
          }
        },
        "required": [
          "addresses",
          "dates_of_birth",
          "genders",
          "nationalities",
          "places_of_birth"
        ],
        "type": "object"
      },
      "ps_ProfileField": {
        "description": "Raw provider field preserved for transparency.",
        "properties": {
          "name": {
            "description": "Provider field name, when supplied.",
            "nullable": true,
            "type": "string"
          },
          "source": {
            "description": "Provider field source, when supplied.",
            "nullable": true,
            "type": "string"
          },
          "tag": {
            "description": "Provider field tag, when supplied.",
            "nullable": true,
            "type": "string"
          },
          "value": {
            "description": "Provider field value.",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "ps_ProviderDetail": {
        "description": "Provider-specific detail payload for a risk.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ps_MatcherDetail"
          }
        ],
        "type": "object"
      },
      "ps_Risk": {
        "description": "Single payment screening risk entry.",
        "properties": {
          "created_at": {
            "description": "UTC timestamp when the risk was created.",
            "example": "2024-07-18T10:29:45.453Z",
            "format": "date-time",
            "type": "string"
          },
          "detail": {
            "$ref": "#/components/schemas/ps_RiskDetail"
          },
          "identifier": {
            "description": "Unique identifier of the risk.",
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "description": "Current review status of the risk.",
            "enum": [
              "NOT_REVIEWED",
              "IN_REVIEW",
              "FALSE_POSITIVE",
              "TRUE_POSITIVE"
            ],
            "type": "string"
          },
          "type": {
            "description": "External risk type exposed by the payment screening API.",
            "enum": [
              "NAME",
              "BIC",
              "TEXT"
            ],
            "nullable": true,
            "type": "string"
          },
          "updated_at": {
            "description": "UTC timestamp when the risk was last updated.",
            "example": "2024-07-18T10:29:45.453Z",
            "format": "date-time",
            "type": "string"
          },
          "updated_by": {
            "description": "Identifier of the user who last updated the risk.",
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "created_at",
          "detail",
          "identifier",
          "status",
          "updated_at",
          "updated_by"
        ],
        "type": "object"
      },
      "ps_RiskDetail": {
        "description": "Provider-agnostic detail for a payment screening risk.",
        "properties": {
          "configuration_identifier": {
            "description": "Configuration identifier that produced the screening result, when available.",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "provider_detail": {
            "$ref": "#/components/schemas/ps_ProviderDetail"
          },
          "relevance": {
            "description": "Relevance classification for the screening hit.",
            "enum": [
              "EXACT_NAME",
              "EXACT_AKA",
              "SIMILAR_NAME",
              "SIMILAR_AKA",
              "BIC_MATCH",
              "EXACT_EQUIVALENT",
              "SIMILAR_EQUIVALENT",
              "UNKNOWN"
            ],
            "type": "string"
          },
          "screened_entity_info": {
            "$ref": "#/components/schemas/ps_ScreenedEntityInfo"
          },
          "screening_context": {
            "$ref": "#/components/schemas/ps_ScreeningContext"
          },
          "source_type": {
            "description": "Classification of this individual screening hit: SANCTION, CUSTOM_LIST, RISK_WORD_LIST, PEP or WATCHLIST.",
            "enum": [
              "SANCTION",
              "CUSTOM_LIST",
              "RISK_WORD_LIST",
              "PEP",
              "WATCHLIST"
            ],
            "type": "string"
          }
        },
        "required": [
          "provider_detail",
          "relevance",
          "screened_entity_info",
          "screening_context",
          "source_type"
        ],
        "type": "object"
      },
      "ps_RiskResponse": {
        "description": "Paginated response envelope for transaction risk results.",
        "properties": {
          "first": {
            "description": "Canonical URL for the first page, when available.",
            "nullable": true,
            "type": "string"
          },
          "next": {
            "description": "Canonical URL for the next page, when available.",
            "nullable": true,
            "type": "string"
          },
          "prev": {
            "description": "Canonical URL for the previous page, when available.",
            "nullable": true,
            "type": "string"
          },
          "risks": {
            "description": "Risk records returned for the current page.",
            "items": {
              "$ref": "#/components/schemas/ps_Risk"
            },
            "type": "array"
          },
          "self": {
            "description": "Canonical URL for the current page.",
            "type": "string"
          },
          "total_count": {
            "description": "Total number of risks available across all pages.",
            "format": "int32",
            "type": "integer"
          }
        },
        "required": [
          "risks",
          "self",
          "total_count"
        ],
        "type": "object"
      },
      "ps_ScreenedEntityInfo": {
        "description": "Information about the screened entity that produced the risk.",
        "properties": {
          "index": {
            "description": "Index of the screened entity within the original request, when applicable.",
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "type": {
            "description": "Type of entity field that was screened.",
            "enum": [
              "DEBTOR_NAME",
              "ULTIMATE_DEBTOR_NAME",
              "CREDITOR_NAME",
              "ULTIMATE_CREDITOR_NAME",
              "AGENT_BANK_NAME",
              "AGENT_MONEY_TRANSFER_OPERATOR_NAME",
              "AGENT_ONLINE_REMITTANCE_PLATFORM_NAME",
              "AGENT_BANK_BIC",
              "AGENT_MONEY_TRANSFER_OPERATOR_BIC",
              "AGENT_ONLINE_REMITTANCE_PLATFORM_BIC",
              "AGENT_VIRTUAL_ASSET_SERVICE_PROVIDER_NAME",
              "FINANCIAL_DETAILS_REFERENCE",
              "AGENT_REFERENCE",
              "CARD_HOLDER_NAME",
              "MERCHANT_NAME",
              "SUB_MERCHANT_NAME",
              "ISSUER_NAME",
              "ACQUIRER_NAME",
              "WALLET_MANAGING_EXCHANGE_NAME",
              "CREDITOR_BIC",
              "DEBTOR_BIC",
              "ULTIMATE_CREDITOR_BIC",
              "ULTIMATE_DEBTOR_BIC",
              "CARD_HOLDER_BIC",
              "MERCHANT_BIC",
              "SUB_MERCHANT_BIC",
              "ISSUER_BIC",
              "ACQUIRER_BIC"
            ],
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "ps_ScreeningContext": {
        "description": "Context surrounding the screening operation that produced the risk.",
        "properties": {
          "customer_identifier": {
            "description": "Customer identifier associated with the screening operation.",
            "format": "uuid",
            "type": "string"
          },
          "number_of_results": {
            "description": "Number of results returned by the provider for the search.",
            "format": "int32",
            "type": "integer"
          },
          "search_term": {
            "description": "Search term submitted to the screening provider.",
            "type": "string"
          },
          "source_list_type": {
            "description": "Type of source list set that was screened.",
            "enum": [
              "SANCTION",
              "CUSTOM_LIST",
              "RISK_WORD_LIST",
              "INTERNAL"
            ],
            "type": "string"
          }
        },
        "required": [
          "customer_identifier",
          "number_of_results",
          "search_term",
          "source_list_type"
        ],
        "type": "object"
      },
      "ps_SourceNote": {
        "description": "Per-source note attached to the matched profile.",
        "properties": {
          "aml_types": {
            "description": "AML types associated with the source note.",
            "items": {
              "description": "AML type assigned by the screening provider.",
              "enum": [
                "SANCTION",
                "WARNING",
                "FITNESS_PROBITY",
                "PEP",
                "PEP_CLASS_1",
                "PEP_CLASS_2",
                "PEP_CLASS_3",
                "PEP_CLASS_4",
                "ADVERSE_MEDIA",
                "ADVERSE_MEDIA_FINANCIAL_CRIME",
                "ADVERSE_MEDIA_VIOLENT_CRIME",
                "ADVERSE_MEDIA_SEXUAL_CRIME",
                "ADVERSE_MEDIA_TERRORISM",
                "ADVERSE_MEDIA_FRAUD",
                "ADVERSE_MEDIA_NARCOTICS",
                "ADVERSE_MEDIA_GENERAL",
                "UNKNOWN"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "country_codes": {
            "description": "Country codes associated with the source note.",
            "items": {
              "description": "Country codes associated with the source note.",
              "type": "string"
            },
            "type": "array"
          },
          "listing_ended_at": {
            "description": "UTC timestamp when the listing ended, when available.",
            "example": "2024-07-18T10:29:45.453Z",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "listing_started_at": {
            "description": "UTC timestamp when the listing started, when available.",
            "example": "2024-07-18T10:29:45.453Z",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "name": {
            "description": "Display name of the source note.",
            "type": "string"
          },
          "source_identifier": {
            "description": "Provider source identifier associated with the note, when available.",
            "nullable": true,
            "type": "string"
          },
          "source_key": {
            "description": "Key of the source note entry.",
            "type": "string"
          },
          "url": {
            "description": "Source URL associated with the note, when available.",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "aml_types",
          "country_codes",
          "name",
          "source_key"
        ],
        "type": "object"
      },
      "ps_TextMatchTerm": {
        "description": "Matched text fragment for text screening results.",
        "properties": {
          "matching_reason": {
            "description": "Reason reported by the provider for the text match.",
            "type": "string"
          },
          "name_type": {
            "description": "Name type of the matched term (e.g. aka, homophone).",
            "type": "string"
          },
          "source_name": {
            "description": "Name of the source that produced the text match.",
            "type": "string"
          },
          "substring_matched": {
            "default": null,
            "description": "Inclusive start and end offsets of the substring match, when available.",
            "items": {
              "description": "Inclusive start and end offsets of the substring match, when available.",
              "format": "int32",
              "type": "integer"
            },
            "nullable": true,
            "type": "array"
          },
          "term": {
            "description": "Query term that matched, as keyed in the provider's text match payload.",
            "type": "string"
          }
        },
        "required": [
          "matching_reason",
          "name_type",
          "source_name",
          "term"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "description": "HTTP Bearer Token Authentication",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "Mesh API",
    "version": "v2.0"
  },
  "openapi": "3.0.3",
  "paths": {
    "/v2/payment-screening/risks": {
      "get": {
        "description": "Retrieve all payment-screening risks attached to a single transaction. The transaction is addressed by exactly one of two mutually exclusive query parameters: `transaction_identifier` (the internal ComplyAdvantage payment identifier, a UUID) or `transaction_external_identifier` (the client's own external payment reference, an arbitrary string). Supplying both, or neither, is a 400. Returns a 200 with an empty `risks` array when the transaction exists but produced no risks. Results are ordered by `created_at` ascending; ties are broken by risk `identifier`.\n\n\nYou need \"Access to base payment screening functionality\" enabled to use this endpoint.",
        "operationId": "paymentScreeningGetRisksByTransaction",
        "parameters": [
          {
            "description": "Internal ComplyAdvantage payment identifier (UUID). Mutually exclusive with transaction_external_identifier.",
            "example": "9f2a7c10-3e44-4b21-bc55-1d0a9e6f2b88",
            "in": "query",
            "name": "transaction_identifier",
            "required": false,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "description": "Client's own external payment reference. Mutually exclusive with transaction_identifier.",
            "example": "client-txn-9f2a",
            "in": "query",
            "name": "transaction_external_identifier",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "1-based page index",
            "example": 1,
            "in": "query",
            "name": "page_number",
            "required": false,
            "schema": {
              "default": 1,
              "format": "int32",
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Page size (max 100)",
            "example": 25,
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "default": 25,
              "format": "int32",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ps_RiskResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ps_ProblemDetailErrorResponse"
                }
              }
            },
            "description": "Conflicting or missing identifier, or invalid pagination parameters"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ps_ProblemDetailErrorResponse"
                }
              }
            },
            "description": "Not found"
          }
        },
        "summary": "Retrieve risks for a transaction",
        "tags": [
          "Payment Screening"
        ]
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "servers": [
    {
      "description": "ComplyAdvantage Mesh API",
      "url": "https://api.mesh.complyadvantage.com"
    }
  ],
  "tags": [
    {
      "name": "Payment Screening"
    }
  ]
}
```