This page leads you through the following steps to register and deregister parties in order to create prediction results:
- Ensure you're ready to register parties
- Prepare the party registration tables
- Use the
projects.locations.instances.importRegisteredParties
method to register or deregister parties - Validate the method response
- (Optional) Export a table of registered parties
Before you begin
Before you begin, you need an AML AI instance.
To enable a model to create risk score predictions, you must first register parties. We recommend that you register parties when you already have the following:
- One or more datasets
- A tuned, trained, and backtested model
When to register parties
Before you can create predictions for a party in one of your datasets, you need to register the party. Registration is not required for training, tuning, or backtesting.
Prediction results are used in investigating customers for money laundering in either a production or testing (parallel) phase. You may also want to build your own governance and model analysis processes around the results you obtain from predictions.
Registering parties incurs additional monthly costs per registered party (see the Pricing page for more information).
How to prepare party registration tables
Read the Pricing page for information on registering parties.
Prepare a table for the line of business you want to register parties for. If you have some parties registered already, this party registration table could contain a subset of the parties from the Party table that you want to use for prediction results.
Retail parties schema
Column | Type | Description |
---|---|---|
party_id | STRING | Unique identifier of the party in the instance's datasets |
party_size | STRING | NULL; content is ignored for retail party registrations |
Commercial parties schema
Column | Type | Description |
---|---|---|
party_id | STRING | Unique identifier of the party in the instance's datasets |
party_size | STRING |
Requested party size. The tier is based on the average number of monthly transactions for
the party over the preceding 365 days:
All values are case sensitive. |
How to register parties
Parties are registered separately for each AML AI instance. Note the following:
- Retail and commercial parties must be registered separately. Use separate API calls and separate party registration tables. If a party is in both lists, they are considered separate registrations.
- Predictions require all parties to be registered with the line of business associated with the engine version used. You can't create prediction results if a dataset is used that contains any party not registered with the same line of business.
- The provided party registration table is used to either append to the existing list of registered parties in the instance or replace all registered parties for the provided line of business in the instance.
- Once registered, a party can't be deregistered for some time (see the
Pricing page). For this reason, you can set the
validateOnly
field toTRUE
. This field allows you to see the net effect and response of the method without changing the registered parties. Once validated, you can rerun the operation and set thevalidateOnly
parameter toFALSE
. - Always check the response of a registration request to ensure all parties
were registered successfully, even if a previous
validateOnly
request succeeded. - For commercial party registrations, a value other than
SMALL
orLARGE
in theparty_size
field in the party registration table triggers an error (Invalid party_size present in table
). Registered parties are not updated. - For retail party registrations, the
party_size
field is ignored and all parties in the provided party registration table are registered.
To import registered parties, use the
projects.locations.instances.importRegisteredParties
method.
(The following information is also available in Create and manage instances.)
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: the user-defined identifier for the instanceBQ_INPUT_REGISTERED_PARTIES_DATASET_NAME
: a BigQuery dataset that contains a table that describes the registered partiesPARTY_REGISTRATION_TABLE
: the table that lists the registered partiesUPDATE_MODE
: useREPLACE
to replace parties that are removable in the registered parties table with new parties, or useAPPEND
to add new parties to the registered parties tableLINE_OF_BUSINESS
: this field must match thelineOfBusiness
value in the engine version used by the engine config; useCOMMERCIAL
for commercial banking customers (legal and natural entities), or useRETAIL
for retail banking customers
Request JSON body:
{ "partyTables": [ "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE" ], "mode": "UPDATE_MODE", "lineOfBusiness": "LINE_OF_BUSINESS" }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "partyTables": [ "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE" ], "mode": "UPDATE_MODE", "lineOfBusiness": "LINE_OF_BUSINESS" } EOF
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:importRegisteredParties"
PowerShell
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "partyTables": [ "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE" ], "mode": "UPDATE_MODE", "lineOfBusiness": "LINE_OF_BUSINESS" } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:importRegisteredParties" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "importRegisteredParties", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For information on how to get the result of the long-running operation (LRO), see Manage long-running operations.
Registration response
When the LRO completes, the response indicates the number of parties that were added, removed, or updated by the operation.
Response field | Type | Description |
---|---|---|
partiesAdded | integer |
Number of parties added by this operation |
partiesRemoved | integer |
Number of parties removed by this operation |
partiesTotal | integer |
Total number of parties that are registered in this instance, after the update operation was completed |
partiesUptiered | integer |
Total number of commercial parties that are uptiered from small to large |
partiesDowntiered | integer |
Total number of commercial parties that are downtiered from large to small |
partiesFailedToDowntier | integer |
Total number of commercial parties that failed to downtier from large to small |
partiesFailedToRemove | integer |
Number of parties that failed to be removed by this operation |
How to deregister parties
Parties are deregistered per AML AI instance using the same
projects.locations.instances.importRegisteredParties
method and replacing the existing list of parties. Set the mode
field to
REPLACE
. This setting deregisters any currently registered parties (for
the provided line of business) that are not part of the provided party
registration table.
Deregistration responses
After the operation completes, check the API response to check if the operation led to the intended result in terms of numbers of parties added or removed, and the total number of registered parties.
The API response also returns the number of parties which couldn't be removed due to constraints; for example, a customer can't be deregistered until a minimum number of days has passed.
Export registered parties
To export registered parties, use the
projects.locations.instances.exportRegisteredParties
method.
(The following information is also available in Create and manage instances.)
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: the user-defined identifier for the instanceBQ_OUTPUT_DATASET_NAME
: a BigQuery dataset in which to export a table that describes the registered partiesPARTY_REGISTRATION_TABLE
: the table to write the registered parties toWRITE_DISPOSITION
: the action that occurs if the destination table already exists; use one of the following values:-
WRITE_EMPTY
: Only export data if the BigQuery table is empty. -
WRITE_TRUNCATE
: Erase all existing data in the BigQuery table before writing to the table.
-
LINE_OF_BUSINESS
: useCOMMERCIAL
for commercial banking customers (legal and natural entities), or useRETAIL
for retail banking customers
Request JSON body:
{ "dataset": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE", "writeDisposition": "WRITE_DISPOSITION" }, "lineOfBusiness": "LINE_OF_BUSINESS" }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "dataset": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE", "writeDisposition": "WRITE_DISPOSITION" }, "lineOfBusiness": "LINE_OF_BUSINESS" } EOF
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:exportRegisteredParties"
PowerShell
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "dataset": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE", "writeDisposition": "WRITE_DISPOSITION" }, "lineOfBusiness": "LINE_OF_BUSINESS" } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:exportRegisteredParties" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "exportRegisteredParties", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For information on how to get the result of the long-running operation (LRO), see Manage long-running operations.
This method outputs a BigQuery table with the following schema:
Column | Type | Description |
---|---|---|
party_id | STRING | Unique identifier of the party in the instance's datasets |
party_size | STRING |
Specifies the tier for commercial customers (large versus small). This field does not apply
to retail customers.
All values are case sensitive. |
earliest_remove_time | STRING | The earliest time at which the party can be removed |
party_with_prediction_intent | STRING | The indicator that suggests if a party has been predicted on since the registration |
registration_or_uptier_time | STRING | The time at which the party was registered or uptiered |