Learn about input and output data

Input record data

The input data relates to the individual or organization screened for sanctions or existence on Public Exposed Persons (PEP) lists. The Business Process uses this data as input for screening.

Various screening systems may need different fields. For example, Dow Jones (DJ) only requires the value from input_full_name.

Remember to provide the data as a CSV file.

info

Note that the model only works if your input data includes mandatory parameters. See the corresponding column in the table below.

Field	Description	Example
input_id	Customer record ID	1111
input_record_type	Record type: Individual Organization Securities Any other string is treated as Unknown.	Individual
input_category	Category of the sanctioned, high-risk, or politically exposed entity.	PEP new business parallel production obligatory review high-risk
input_gender	Gender of the Individual type in the record: Male Female Any other string is treated as Unknown.	MALE
input_full_name	Full name of the screened record.	Kasim Rimsevi
input_alias_name*	Name or alias name of the record.	Kasim Ibragim Rimsevi
input_date_{i} input_date_type_{i}	Any date related to the screening record: input_date_{i} should contain the actual date in the MM/DD/YYYY format. input_date_type_{i} should contain the corresponding date type.	10/26/1981 (MM/DD/YYYY) DOB
input_address_{i}_country input_address_{i}_state input_address_{i}_city input_address_{i}_street input_address_{i}_type input_address_{i}_full	Address information related to the screened record.	country: USA state: CA city: Sacramento street: 3930 W Land Park Dr type: citizenship full: 3930 W Land Park Dr, Sacramento, CA 95822, United States
input_*_extdata**	Additional customer data	input_additional_info_extdata
input_*_identifier***	Identifiers or unique pieces of information included in the input data that can be used for model matching but do not fit into any of the standard fields (such as name, gender, location, date, and so on)	SSN Passport number IBAN

* You can add any number of available names. If there are more than two names, use an index or insert a unique segment in the middle of the field, for example:

• input_alias_name, input_aka_name, input_synonym_name

• input_alias1_name, input_alias2_name, …

** It is possible to add multiple values for additional data. If there are more than two values, use an index or insert a unique segment in the middle of the field, for instance:

• input_additional_extdata, input_hair_color_extdata, …

• input_additional_1_extdata, input_additional_2_extdata, …

*** It is possible to add multiple values for identifiers. If there are more than two values, use an index or insert a unique segment in the middle of the field, for instance:

• input_ssn_identifier, input_passport_number_identifier, …

• input_id_1_identifier, input_id_2_identifier, …

Watchlist entity data

Watchlist entity (WLE) data comes from screening systems like Doe Jones, World Check One (WC1), Firco Trust (FT), and so on.

Field	Description	Example
hit_id	ID of the sanctioned, high-risk, or politically exposed individual alert.	1362545
hit_record_type	Record type of the sanctioned, high-risk, or politically exposed entity.	Person
hit_category	Category of the sanctioned, high-risk, or politically exposed entity.	PEP new business parallel production obligatory review high-risk
hit_gender	Gender of the sanctioned, high-risk, or politically exposed individual.	Male
hit_matched_name	The partial name from a sanctions or PEP list detected as a potential match by the screening software of the sanctioned, high-risk, or politically exposed entity.	Qasim Al-Rimi
hit_alias_name*	Name or alias name of the sanctioned, high-risk, or politically exposed entity.	Qasim Muhammed
hit_date_type_{i} hit_date_{i}	Date information of a hit entity. Usually, DOB (date of birth) or DOR (date of registration). It can be a partial date.	06/15/1978, 06/14/1978 (MM/DD/YYYY), 09/1994, 1944
hit_address_{i}_country hit_address_{i}_state hit_address_{i}_city hit_address_{i}_street hit_address_{i}_type hit_address_{i}_full	Address information of a hit entity.	country: USA state: CA city: Sacramento street: 3930 W Land Park Dr type: citizenship full: 3930 W Land Park Dr, Sacramento, CA 95822, United States
hit_*_extdata**	Additional hit entity data	hit_additional_info_extdata
hit_*_identifier***	Identifiers or unique pieces of information included in the input data that can be used for model matching but do not fit into any of the standard fields (such as name, gender, location, date, and so on)	SSN Passport number IBAN

* You can add any number of available names. If there are more than two names, use an index or insert a unique segment in the middle of the field, for example:

• hit_alias_name, hit_aka_name, hit_primary_name

• hit_alias1_name, hit_alias2_name, …

** It is possible to add multiple values for additional data. When there are more than two values, use an index or insert a unique segment in the middle of the field, for instance:

• hit_additional_extdata, hit_hair_color_extdata, …

• hit_additional_1_extdata, hit_additional_2_extdata, …

*** It is possible to add multiple values for identifiers. If there are more than two values, use an index or insert a unique segment in the middle of the field, for instance:

• hit_ssn_identifier, hit_passport_number_identifier, …

• hit_id_1_identifier, hit_id_2_identifier, …

Model decision data per hit entity

The Name Sanctions Screening AI Agent matches inputs and tries to ascertain whether the generated hit is indeed a true hit, one of the many generated false hits, or if the provided information is insufficient for the decision. The matching logic inside the process informs the output fields.

Field	Description
resolution_input_decision	Overall decision for full alert or case. No hits: there are no hit entities for the screened record. Needs further review: at least one hit entity is marked as Need more information. Cleared Alert: all hit entities are marked as False positive.
resolution_input_details	Details on the status explanation. Contains data about the number of hits marked as False positive or Need more information.
resolution_hit_decision	Machine Learning (ML) model decision. 0: False positive 1: Need more information
resolution_hit_confidence	ML model's confidence in the taken decision.
resolution_hit_explanation	Human-readable explanation of the model decision.
resolution_hit_field_type	ML model's decision on the record type field: 0: mismatch 1: match 2: not enough information
resolution_hit_field_name	ML model's decision on the name field, name matching similarity. Possible values from 0..1, where: 1: full match 0: mismatch
resolution_hit_field_gender	ML model's decision on the gender field: 0: mismatch 1: match 2: not enough information
resolution_hit_field_date	ML model's decision on the date field: 0: mismatch 1: match 2: not enough information
resolution_hit_field_address	ML model's decision on the address field: 0: mismatch 1: match 2: not enough information

Output contract

You can invoke the core Names Screening Business Process in two primary ways:

• External communication (via HTTP clients like Postman or cURL)

• Internal communication (BP to BP, within the platform)

External communication

For external communication, the AlertResponse Data Transfer Object (DTO) is exposed. The exposed data is restricted to protect sensitive internal details.

The response is a sanitized JSON object containing the following fields:

Field name	Description	Source
inputId	Unique identifier for the alert decision or input.	alertDecision.getId()
clientId	Client identifier associated with the transaction.	clientId
alertResolution	Final alert resolution, for example, RELEASE or POTENTIAL.	alertDecision.getResolution() (readable value)
alertExplanation	Explanation or reasoning behind the resolution.	alertDecision.getExplanation()
hits	List of associated hits (matches).	List of HitResponse objects
qcReportLink	Link to the quality check report (if available).	qcReports.getReportLink()
htmlReportLink	Link to the HTML report (if available).	htmlReportLink

Each item in the hits list includes the following fields:

• hitId: unique identifier for the hit.

• hitResolution: resolution for the specific hit.

• hitExplanation: explanation for the hit resolution.

• hitScore: match score.

The response also includes worker details (workerId, workerFirstName, and workerLastName) if they are present in the input task data. This helps track manual review outcomes.

When the provider is Firco Trust, a specialized response format is used. This logic takes precedence over the standard external communication if the provider identifier matches.

The response focuses on report links extracted from the input data.

Field name	Type	Description
report_link	List<String>	List of report links aggregated from the input data.

Internal communication

For internal communication, such as when one connector invokes the Names Screening BP directly, a more comprehensive data set is returned. This allows the calling connector to parse the results and utilize internal processing data that is not suitable for external exposure.

The internal result includes the following fields:

Field name	Type	Description
wle_list	List	Full list of WLEs.
screened_data	ScreenedData	Original data that was screened.
alert_resolution	String	Raw alert resolution value, for example, POTENTIAL or FALSE_POSITIVE.
auto_qc	Boolean	Flag indicating whether automatic quality check was performed.
html_report_link	String	URL to the generated HTML report.
qc_reports	QcReportDTO	Detailed QC report object.

Quality Check report

Each Business Process execution produces a Quality Check (QC) report containing information for further human review or reconciliation. The report is saved in MinIO S3 under doc-upload/name-sanctions-screening/QC_Reports/{year}/{month}/ QC_Names-Screening-<<yyyy-MM-dd_HH-MM-SS>>.csv.

A QC report contains input as customer information, hit data found in the screening system, and records specific to the screening system. The timestamp in the report name indicates the time when the BP was run.

note

• By default, you might not have permission to access the S3 bucket. To get the permissions, create a Support ticket.

• In case a QC report contains large data amounts, it is divided and saved in several parts, where each part is no more than 50 MB large.

The QC report contains the following columns:

Input Data columns
input_id	FT: system_id WC1: case_system_id DJ/CSV: input_id submitted in the input file
input_full_name	FT: the first name in the Customer Information names WC1/DJ/CSV: input_full_name submitted in the input file
input_country	Aggregated information containing all submitted addresses. Format: Type1 Country1 State1 City1 Street1 | Type2 Country2 State2 City2 Street2 Example: Citizenship GBR London | Jurisdiction GBR | Resident of GBR
input_date	Aggregated submitted date information. Format: mm/dd/yyyy | mm/dd/yyyy ….
input_gender	Gender of the Individual type in the record. Otherwise, empty.
input_type	Type of the record. Otherwise, empty.
Firco Trust CMAPI specific columns
firco_bussiness_unit	Firco Trust Alert Business Unit value.
firco_unit	Firco Trust Alert Unit value.
firco_system_id	Firco Trust Alert system_id value.
firco_message_id	Firco Trust Alert message_id value.
record_matching_string	Firco Trust Hit Entity record_matching_string value.
list_matching_string	Firco Trust Hit Entity list_matching_string value.
World Check-One specific columns
case_system_id	World Check-One Case system_id value.
group_id	World Check-One group_id.
Historical Data specific columns
hit_gold_resolution
Hit data columns
hit_id	FT/WC1/DJ: hit ID for the sanctioned entity CSV: hit_id submitted in the input file
hit_full_name	FT/WC1/DJ: name of the sanctioned entity detected as a potential match CSV: hit_matched_name submitted in the input file
hit_country	Aggregated information containing all submitted address data of the sanctioned entity. Format: Type1 Street1 City1 State1 Country1 FullAddress1 | Type2 Street2 City2 State2 Country2 FullAddress2 Example: Citizenship London GBR | Jurisdiction GBR | Resident of GBR
hit_date	Aggregated submitted date information. Format: `mm/dd/yyyy
hit_gender	Gender of the Individual type in the record. Otherwise, empty.
hit_type	Type of the record. Otherwise, empty.
Model resolution columns
model_decision	ML model decision.
model_explanation	ML model explanation.
alert_decision	Overall decision for the entire alert or case.
alert_explanation	Details on the status explanation. Contains data about the number of hits marked as False positive or Need more information.
decision_score	ML model decision score.
name_similarity	Name matcher results.
Additional information columns
auto_qc	Yes/No flag indicating that a hit is selected for automatic quality check.
input_names	Aggregated information containing all submitted screening names.
hit_names	Aggregated information containing all found WLE names.

The NSS QC report is similar to the sample.