Input and output data

Expected input and output keys

Category	Input key	Input value	Output key	Comments
File (flat)	id, hit_id	Strings		Input consists of multiple columns derived from a request JSON object. Manually collect response from the Data Store or Control Tower output.
File (JSON)	request_json_object	Message		Manually collect response from the Data Store or Control Tower output.
API	rest_request	Message wrapped in request body	rest_response	Response sent to the API caller.
Connector	connector_request	Message	connector_response	Business Process (BP) column for data retrieval.
BP wrapper	message_request	Message	message_response	BP column for data retrieval.

Providing input

Input to the Payment Sanction Screening BP refers to surveillance system alert details triggered against a given payment message or transaction.

Tara supports the following types of input:

• File input
• Streaming API input
• Data from connector

File input

The file input feature allows uploading an input CSV file. A BP finishes when all records are processed.

• A file in the original format contains a JSON request. There are the following columns for execution:

  • request_json_object (required)
  • decision_gold_json_object (optional)

  See pss_request_processing_test_100.csv as a sample.

• A file in the flat format contains unfolded request_json_object, where a BP treats each row as a separate request. Using a CSV flat file as a template is the easiest input method for uploading input data for transaction screening.

  See flat_input_data.csv as a sample.

To upload data, follow the steps:

1. In your BP, go to the Data tab and click the Upload Data button.

   

2. Click Add, find your CSV data file, and click Open. Mind that the template supports up to 250K records. It takes longer to process more records.

   

   input_data.csv is a template you can use to quickly upload data for use with Tara.

3. Click Upload.

   

If you have already run the BP, you might need to copy it. To do that, select the Copy option.

In the Copy window, do not select the Include the input data option. Then, you can add a new CSV file to your copied BP.

Streaming API input

The system obtains input data from the built-in streaming service. You can define and update API endpoints. A BP is available even when all records are processed.

To use the built-in streaming service, do as follows:

1. In your BP, go to the Data tab and select the Streaming Records from External Sources option.

2. Specify the external source in the field. For more details, refer to API | Tara.

   

Data from connector

Tara uses the following in-house connectors to communicate with alerting systems:

• LexisNexis Bridger XG Connector

• Firco Continuity Case Manager API Connector

• Firco Continuity Prediction Integration Connector

Depending on a screening system, there are two options for working with the connectors:

• Install a stand-alone external connector that communicates with Tara using a signal ID.

• Add a connector as a separate step within Tara's core BP.

To select the connector as the source of your input data, go to the Data tab in your BP and click No Data.

Request Data Store

Tara accepts standardized input in JSON-formatted strings and saves requests into the pss_request_processing_v1 Data Store. For more details, see Run screening | Analyze results.

See a sample pss_request_processing_v1 Data Store in the table below.

Column	Description	Example
system_id	Database generated ID.	1
request_id	UUID generated before adding a record to a Data Store.	73116728-493e-4355-875d-78d6d2456f32
request_json_object	Original customer data for adjudication in the JSON format representing a Message object.	See an example below.
decision_json_object	Model Decision in the JSON format representing a MessageDecision object.	See an example below.
decision_gold_json_object	Gold Model Decision in the JSON format representing a MessageDecision object; used for model training and calculating statistics.	See an example below.
message_json_object	Processed or enhanced copy of customer data for adjudication in the JSON format representing a Message object; data from this column is sent to the model for processing.	See the original Message object.
request_insert_time	Insert data timestamp.	Type: LocalDateTimeType—"yyyy-MM-dd HH:mm:ss.SSSX"
last_updated_time	Timestamp of the latest update.	Type: LocalDateTimeType—"yyyy-MM-dd HH:mm:ss.SSSX"
decision	Final message decision.	RESOLVE or NO_DECISION
status	Processing status; updated during record processing.	NEW, IN_PROGRESS, COMPLETED, or FAILED
client_id	User who sent the request for processing.
run_uuid	BP run UUID used for data search and analysis.
tara_version	AI Agent version used for data analysis.
ner_model_version	Version of the NER model.
decision_model_version	Version of the Decision model.
number_of_hits	Number of hits in an alert request.
is_auto_qc	Defines if an alert is marked for auto quality control.

See the example of request_json_object

{
  "id": "test-message-id-6",
  "type": "PAYMENT_TRANSFER",
  "hits": [
    {
      "id": "2001",
      "tagContent": "DOE, J",
      "tagType": "FREETEXT",
      "additionalData": {
        "name": "Doer Jerry",
        "dob": "10/10/1975",
        "address": "10 Bressenden Place, 8th floor",
        "country": "GBR",
        "city": "london",
        "state": "GBR",
        "postal": "SW1E 5DH"
      },
      "sanctionData": {
        "name": "doe, john",
        "type": "INDIVIDUAL",
        "country": "syrian arab republic",
        "sourceEntryId": "1111",
        "source": "OFAC",
        "listType": "WORLD_COMPLIANCE"
      }
    },
    {
      "id": "2002",
      "tagContent": "DOE, J",
      "tagType": "FREETEXT",
      "additionalData": {
        "name": "Doer Jerry",
        "dob": "10/10/1975",
        "address": "10 Bressenden Place, 8th floor",
        "country": "GBR",
        "city": "london",
        "state": "GBR",
        "postal": "SW1E 5DH"
      },
      "sanctionData": {
        "name": "doe",
        "type": "INDIVIDUAL",
        "country": "US",
        "sourceEntryId": "2222",
        "source": "OFAC",
        "listType": "WORLD_COMPLIANCE",
    "primaryName": "Jerry Samuel Doe"
    "alsoKnownAs": [
      {"name": "doe", "type": "STRONG"},
      {"name": "JD", "type": "WEAK"},
      {"name": "Sam", "type": "NOT_AVAILABLE"}
    ]
      }
    }
  ]
}

See the example of decision_json_object

{
  "messageId": "test-message-id-6",
  "suggestedAction": "RESOLVE",
  "hitDecisions": [
    {
      "hitId": "2001",
      "suggestedAction": "RESOLVE",
      "comment": "Name mismatch. Screened entity name \"Doer Jerry\" does not match Watch List Entity name \"doe, john\";,Country mismatch. Screened entity location \"GBR\" does not match Watch List Entity location \"syrian arab republic\";",
      "reasons": [
        {
          "code": "2",
          "description": "Name mismatch. Screened entity name \"Doer Jerry\" does not match Watch List Entity name \"doe, john\";",
          "score": 1.0
        },
        {
          "code": "3",
          "description": "Country mismatch. Screened entity location \"GBR\" does not match Watch List Entity location \"syrian arab republic\";",
          "score": 1.0
        }
      ]
    },
    {
      "hitId": "2002",
      "suggestedAction": "RESOLVE",
      "comment": "Name mismatch. Screened entity name \"Doer Jerry\" does not match Watch List Entity name \"doe, johanna\";,Country mismatch. Screened entity location \"GBR\" does not match Watch List Entity location \"US\";",
      "reasons": [
        {
          "code": "2",
          "description": "Name mismatch. Screened entity name \"Doer Jerry\" does not match Watch List Entity name \"doe, johanna\";",
          "score": 1.0
        },
        {
          "code": "3",
          "description": "Country mismatch. Screened entity location \"GBR\" does not match Watch List Entity location \"US\";",
          "score": 1.0
        }
      ]
    }
  ]
}

See the example of decision_gold_json_object

{
  "messageId": "test-message-id-6",
  "suggestedAction": "RESOLVE",
  "hitDecisions": [
    {
      "hitId": "2001",
      "suggestedAction": "RESOLVE",
      "comment": "Name mismatch. Screened entity name \"Doer Jerry\" does not match Watch List Entity name \"doe, john\",
      "reasons": []
    },
    {
      "hitId": "2002",
      "suggestedAction": "RESOLVE",
      "comment": "Screened entity location \"GBR\" does not match Watch List Entity location \"US\",
      "reasons": []
    }
  ]
}

Input data

See request input parameters in the tables below. For more details, refer to the API documentation.

Request input (flat file)

The table below is a flat representation of the official sanctions API client JSON.

Field	Description	Required	Example
id	Alert ID generated by the screening system.	Yes	110981894
type	Payment message type.	No	SWF
subtype	Payment message subtype.	No	103
content	Full payment message content in the specified format. Must be accompanied by the content format.	No	{1:F01BCITITMMBXXX0000000000} {2:I103TGBATRISXXXXN} {3: {108:2018072701224102} {119:STP} {111:001} {121:78495885-03a7-43dd-a2e7-18a433086d92}} {4: :20:52937187279307RB :23B:CRED :32A:180730EUR1500, :33B:EUR1500, :50K:/IT26S0306933090100000003191 CASTIGLIONI SRL VIA ACHILLE GRANDI,2 20020 ARCONATE (MI) :53A:BCITITMM :59:/TR240006200012000009097610 DANTEKS DANTEL VE TUL ORME SAN TIC BOLGESI MUSTAFA TR HADIMKOY :70:ACCONTO ORDINE :71A:SHA -}
content_format	Format in which the payment message is sent. To parse the message content, the field can be used instead of the type field: SWIFT_MT format = SWF type + NATIVE format SWIFT_MT format = ISO_20022 type + NATIVE format	No (Yes if the content field is provided)	SWIFT_MT
customAttributes	Map of alert-level custom attributes. The attributes are not used in processing but can be used in rules.	No

Hit details

Field	Description	Required	Example
hit_id	Hit ID generated by the screening engine. Used to identify a hit. Must be unique per alert.	Yes	12345
hit_tagcontent	Text containing the hit value from hit_tagname. Typically, includes hit_hittext.	No (Yes if there is no message content)	/IT26S0306933090100000003191 CASTIGLIONI SRL VIA ACHILLE GRANDI,2 20020 ARCONATE (MI)
hit_tagname	Name of the tag containing matched text. Messages can contain multiple tags.	No (Yes if content is used and parsing is needed)	50K
hit_tagtype	Indicates the type of data contained in the tag. Supported values: NAME, NAMEADDRESS, ADDRESS, FREETEXT (used if unknown). A value can be set according to the type dictionary.	Yes	NAMEADDRESS
hit_hitstartindex	Start position of hit_hittext (related to the tag content).	No	30
hit_hitendindex	End position of hit_hittext (related to the tag content)	No	40
hit_hittext	Provides the exact part of the text that triggered the hit. If not provided, a sanction name is used to identify where the hit is within hit_tagcontent. Improves adjudication quality if provided.	No	CASTIGLIONI
hit_hittype	Hit type from the screening system.	No	NAME

Hit screened data

Information about screened entities is used to compare against sanction data. If it exists, it is treated as true values—not parsed and not preprocessed. The object can be populated during alert content parsing.

Field	Description	Required	Example
hit_screeneddata_type	Type of entity if known.	No	ORGANIZATION
hit_screeneddata_name	Contains the value if the hit was on the name.	No	CASTIGLIONI SRL
hit_screeneddata_dob	Date of birth for an individual. Preferred format: MM/dd/yyyy.	No	10/24/1997
hit_screeneddata_address	Address information if relevant to the screened entity.	No	VIA ACHILLE GRANDI,2 20020 ARCONATE (MI)
hit_screeneddata_country	Country information if relevant to the screened entity. Can contain multiple pipe-separated values.	No
hit_screeneddata_city	City information if relevant to the screened entity. Can contain multiple pipe-separated values.	No	ARCONATE
hit_screeneddata_state	State information if relevant to the screened entity.	No	MI
hit_screeneddata_postal	Postal code if relevant to the screened entity.	No
hit_screeneddata_id	Identification number if the hit was on an ID.	No
hit_screeneddata_code_type	Identification name relevant to the screened entity.	No	SSN
hit_screeneddata_code_number	Identification value relevant to the screened entity.	No	111-22-3333
hit_screeneddata_locations	Additional list of location objects. Not represented in a flat file.	No

Hit sanction data

Hit sanction data (required) contains details of the Watch List Entity associated with the hit.

Field	Description	Required	Example
hit_sanctionsdata_name	Sanctioned name that matches the content.	Yes
hit_sanctiondata_primaryName	Primary name of the sanctioned entity.	No
hit_sanctiondata_type	Entity type of the WLE.	Yes (Only defined or null values allowed)	ORGANIZATION
hit_sanctiondata_dob	Date of birth for the WLE. Can contain multiple values separated by the pipe character.	No
hit_sanctiondata_address	Address of the sanctioned entity, if available.
hit_sanctiondata_city	City relevant to the WLE. Can contain multiple values separated by the pipe character.	No
hit_sanctiondata_country	Country associated with the WLE. Can contain multiple values separated by the pipe character.	No
hit_sanctiondata_state	State relevant to the WLE.	No
hit_sanctiondata_sourceEntryID	Value relevant to the WLE source details. Used in the CLDS flow.	No
hit_sanctiondata_source	Value relevant to the WLE source details. Not used in the Decision model.	No
hit_sanctiondata_sourcekeywords	Pipe-separated values relevant to the WLE source details. Used in CLDS reporting but not in the Decision model.
hit_sanctiondata_listType	Value relevant to the WLE source details. Not used in the Decision model.	No
hit_sanctiondata_additionalInfo	Additional information relevant to the WLE source details. Not used in the Decision model.	No
hit_sanctiondata_alsoknownas_name	Alias name for the entity. Can contain multiple values separated by the pipe character.	No
hit_sanctiondata_alsoknownas_type	Entity type for the alias.	No
hit_sanctiondata_code_type	Identification name relevant to the screened entity.	No	SSN
hit_sanctiondata_code_number	Identification value relevant to the screened entity.	No	111-22-3333
hit_sanctiondata_locations	Additional list of location objects. Not represented in a flat file.	No
customAttributes	Map of alert-level custom attributes. The attributes are not used in processing but can be used in rules.	No

Decision information

Decision information is the key data containing adjudication results. It is used for statistical calculations of the automation rate (AR) and error rate (ER). The recommended parameters are as follows:

Field	Description	Required	Example
gold_decision	Decision for a hit. Must be NO_DECISION or RESOLVE.	No	RESOLVE
gold_decision_comment	Narrative created by the analyst explaining the reasons for the decision. No specific format is expected.	No	Name mismatch: john Doe versus John Silverman. Location mismatch: USA versus SYR.

Payment information

Field	Description	Required	Example
payment_direction	Direction of the transfer. Supported values: INCOMING, OUTGOING.	No	INCOMING
payment_receiver_bic	BIC code of the transfer's receiver.	No	BOFIIE2D
payment_receiver_name	Name of the transfer's receiver.	No	John Doe
payment_receiver_country	Country of the transfer's receiver.	No	USA
payment_sender_bic	BIC code of the transfer's sender.	No	BOFIIE2D
payment_sender_name	Name of the transfer's sender.	No	Jane Doe
payment_sender_country	Country of the transfer's sender.	No	USA
payment_amount	Monetary value of the transfer.	No	123456.77
payment_currency	Currency of the transfer.	No	USD

Request input (JSON file)

The input format is designed for easy reprocessing data from the pss_request_processing_v1 Data Store. The format is used to build synthetic data for testing.

Column	Description
request_json_object	Original request data for adjudication in the JSON format representing a Message object.
decision_gold_json_object	Gold Model Decision in the JSON format representing a MessageDecision object; used for model training and calculating statistics.

Output data

Output data format

You can retrieve a decision by:

• A generated HTML report as text (if you enabled the option during the output configuration) located at doc-upload/payment_sanctions_screening/reports/html

• A generated detailed quality control (QC) report in the CSV format (required executing a QC report) located at doc-upload/payment_sanctions_screening/reports/qc

• From the API output response JSON object

The final model decision is adjudicated by running the default list of rules pre-installed with the package. You can also choose to create custom rules.

The default rules in rules_v1.drl are as follows:

• RESOLVE rules:

  • "dob_mismatch": dates of birth provided are more than a year apart (you can configure the Date of birth matching threshold).

  • "type_mismatch_ind_org": sanctioned and screened entities are an individual and an organization or vice versa.

  • "type_mismatch_wle_vessel": a sanctioned entity is an aircraft or vessel, and a screened entity is not.

  • "type_mismatch_hit_location": a hit is an address, but a sanctioned entity is not a location.

  • "type_mismatch_wle_location": a sanctioned entity is a location, but a screened entity is not.

  • "type_mismatch_hit_account": a hit is an account on the screened side, but a wathlist entity is not an account.

  • "type_mismatch_hit_vessel": a screened entity is a vessel, but a watchlist entity is not.

  • "name_country_mismatch_strong": a mismatch between the entity and watchlist entity names and countries of origin.

  • "name_mismatch_strong": a mismatch between the entity and watchlist entity names.

  • "name_country_mismatch_weak": names are a partial match, but countries of origin differ.

  • "id_mismatch": screened and watchlist entity IDs do not match.

  • "location_mismatch_sender_receiver": sender and receiver locations are the same and differ from the watchlist entity location.

  • "location_mismatch_ind": screened and watchlist entities are individuals with different countries of origin.

  • "location_mismatch_loc": screened and sanctioned entities are different locations on the map.

• NO_DECISION rules:

  • "blacklist_item": a name or a country contains a blacklisted item.

  • "id_match": one or more screened IDs match a sanctioned ID.

  • "bic_match": a sanctioned name contains BIC code information, or ID contains a short company name.

  • "location_match_loc": inferred screened and sanctioned countries are the same.

  • "location_match_part_name": a sanctioned name, country, or city is part of a screened entity name.

  • "id_map_match_on_name": a screened name contains an ID or code matching the sanctioned entity data.

  • "id_match_on_name": one or more screened entity IDs match the sanctioned entity name.

  • "cannot_identify_entity": not enough information is provided to make an informed decision.

• NO_DECISION aftermath rules fire if none of the above rules fired before:

  • "name_match": names associated with screened and sanctioned entities match with a high score, and the screened entity is not an ID or code.
  • "partial_name_match": names associated with screened and sanctioned entities match partially, and the screened entity is not an ID or code.
  • "no_applicable_rules_fired": none of the above rules fired and thus cannot be resolved.

See a sample model result

{
  "score": 1
  "category": "RESOLVE"
  "estimatedAccuracy": 0
  "attrs": {
    "model-decision": {
      "messageId": "58198"
      "suggestedAction": "RESOLVE"
      "hitDecisions": [
        {
          "hitId": "8194965"
          "suggestedAction": "RESOLVE"
          "comment": "Name mismatch. Screened entity name 'Witting-Armstrong Inc.' does not match Watch List Entity name 'Terry, Konopelski and Auer Solutions Inc'"
          "reasons": [
            {
              "code": "type match"
              "description": "Screened entity type <organization> matches watch ..."
            }
            {
              "code": "name mismatch"
              "description": "Name mismatch. Screened entity name 'Witting-Arms..."
            }
            {
              "code": "location match"
              "description": "Screened entity locations <VUT> either matches or ..."
            }
          ]
        }
      ]
    }
  }
}

Decision output

A decision returns as a JSON representation of a MessageProcessingResponse object.

Field	Description	Expectation	Example
messageId	Message identification number.	Mandatory when the request processing status is COMPLETED. Optional if a message is invalid or cannot be processed.
suggestedAction	Message-level suggested action. Set to RESOLVE only if each hit has the RESOLVE action. Otherwise, NO_DECISION.	Mandatory	RESOLVE

Hit decisions

Hit decisions refer to a collection of all decisions per hit. Mandatory when the request processing status is COMPLETED. Optional if the message is invalid or cannot be processed.

Field	Description	Expectation	Example
hit_decision_hitId	Hit identification number.	Mandatory
hit_decision_suggestedAction	Hit-level suggested action. Set to RESOLVE or NO_DECISION.	Mandatory	NO_DECISION
hit_decision_comment	Explanation of the decision, combining all reasons.	Mandatory	"Name mismatch. Screened entity name (Romana J) does not match Watch List Entity (Roman Silverman). Country mismatch. Screened entity location(s) <GBR> does not match Watch List Entity location <Palestinian territory, occupied>"
html_report_link	Generated HTML report link included in the response if configured.

Reasons

Reasons refer to the list of reasons that support the decision. At least one reason is expected.

Field	Description	Expectation	Example
hit_decision_reason_code	Reason codes. Matches the name of the rule that fired during adjudication. Varies based on decision factors.	Mandatory	"Name mismatch"
hit_decision_reason_description	Detailed, human-readable explanation.	Mandatory	"Name mismatch. Screened entity name (Romana J) does not match Watch List Entity (Roman Silverman)"
hit_decision_reason_score	Name matcher score that supports the reasoning.	Mandatory	0.88