Salv AML API (1.0.4)

Welcome to the Salv AML API documentation.

The Salv API is built on HTTP. Our API is RESTful. It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can use your favorite HTTP/REST library for your programming language to use Salv API.

API definition to import into Postman can be downloaded at https://docs.salv.com/api/public.yaml

• 22.07.2024 - 1.0.8
  • Added information about rate limiting to Error handling section
• 10.07.2024 - 1.0.7
  • Updated monitoring-related docs with new scenario type names
• 28.06.2024 - 1.0.6
  • Removed fetch all monitoring alerts endpoint
• 28.05.2024 - 1.0.5
  • Added removal notice to fetch all monitoring alerts endpoint
• 03.11.2023 - 1.0.4
  • Added hits info to ALERT_CREATED webhook payload
• 22.09.2023 - 1.0.3
  • Updated authentication documentation
• 12.05.2023 - 1.0.2
  • Added case management section and endpoint to update alert status
• 09.01.2023 - 1.0.1
  • Specified that IDs of persons and transactions are stored as case-sensitive text values
  • Improved language in overview of three endpoints to create or modify person
• 28.12.2022 - 1.0.0
  • Refactored the API documentation structure and introduced changelog

Contact our sales team at sales@salv.com to sign up for service.

• Client — organisation that is using or intends to use Salv service.
• Client application — application owned by client. Will probably integrate with this API.
• Person — natural person or legal entity, one of the customers of the client.
• Transaction — monetary transaction performed by one of the persons.

While the integration process may wary in each case, on average the steps to use the service look as follows:

• Upload historical persons and transactions data using CSV data upload endpoint.
• Configure client application to upload new persons and transactions automatically using addPerson endpoint and addTransaction endpoint.
• Configure monitoring, screening and risks. That would include monitoring scenarios, risk rules and a number of settings for screening. Currently, most of those things can only be configured through Salv UI. However, some of the configuration is available in open API as well:
  • Custom Lists
• Salv will produce monitoring alerts, screening alerts and risk levels for provided persons and transactions based on configuration provided:
  • Monitoring alerts are created according to configured scenarios
  • Screening alerts are created during Automatic Re-screening and on API calls
  • Risks are calculated on data updates
• In order to receive the data about new screening and monitoring alerts in real time, client would need to configure webhooks. Configuring a webhook will cause Salv to notify client application about a particular event, for example about a creation of a new alert or change of a risk level for any person.

Alternatively, all the monitoring alerts, screening alerts and risk levels are available in Salv UI, along with a lot of features to help manage and organize the process of examining the alerts and risks.

Authentication flow examples

With cURL

$ curl -X POST -u "{clientId}:{clientSecret}" -d "grant_type=client_credentials" "https://app.salv.com/oauth/token"
{
  "access_token": "{yourBearerToken}",
  "expires_in": 1576799999,
  "token_type": "Bearer"
}

With Python Requests

import requests

resp = requests.post('https://app.salv.com/oauth/token', auth=({clientId}, {clientSecret}), data={'grant_type': 'client_credentials'})
print(resp.json())

{
  "access_token": "{yourBearerToken}",
  "expires_in": 1576799999,
  "token_type": "Bearer"
}

• New properties may be added to a representation at any time. Make sure that your API client will ignore any unknown properties.
• Removal or alteration of an existing property will be handled through versioning.

Errors 5XX

All requests which return a response with status code 500-599 should be retried after some interval.

If a retry of a failed request fails again, it should be retried again until it succeeds. Retrying a request that repeatedly fails should be done at increasingly longer interval.

Errors 429

If a request returns a response with status code 429, it means that the client has exceeded the rate limit specified in contract.

The request should be retried after some interval.

1. Format the csv file and add all the mandatory data fields indicated in the User Manual

2. Upload the csv file via API. Note: the upload API response contains the id that will to be used in status check API call (step 3). When a data file has been successfully uploaded, an HTTP response with 202 status code is returned. A response with 202 status code indicates that the file has been uploaded successfully and the system will try to process the data. It does not guarantee that data will be successfully processed.

   What will happen next?

   1. First comes the validation phase:

      1. If the Schemas are added in the UI, then our system will validate the file against the schemas (e.g. if there is a field added with DATE type, then system will validate if the date format is correct)
      2. If no Schemas are added in the UI, then our system will consider all fields as STRING

      Note: during this validation phase we do not check if the transaction has been added to the system before.

      3. If there are any errors, then no data will be uploaded. In this case calling check status API call will return FAILED status and a error message for the the first error encountered. The error message will be in the reason field in a human readable text.
      4. If there are no errors, then the upload phase starts.

   2. Second (if no errors occurred) comes the upload phase: our system will start uploading and saving data in batches of 1000, and in case of transaction file will check for duplicates and if the person is present in the system.

      1. If no errors occur, then the file is uploaded successfully.

      2. If an error occurs, then when step no 3 (check status API call) is done, then:

         1. system will show the first error and give the id of the person or transaction that caused the error.
         2. system will show the id of the last uploaded person or transaction and the id of the first person or transaction that was not uploaded.

         and,

         3. the data following the last uploaded person or transaction will not be uploaded.

   • Example:

     Csv file has 200 000 rows. There is a duplicate id on row 87 456. In validation phase duplicate errors are not checked thus the file will move on to the upload phase. First 87 000 rows are uploaded without any errors. Rows starting from 87 001 will not get uploaded because there is a duplicate error in the batch (the patch of 1000 that gets checked). System will show that there is a duplicate, will show the id of the duplicate Person or Transaction and will show the last uploaded Person or Transaction id and the last id that was not added.

     Example of an upload phase error message:

     {
         "status": "PARTIALLY_COMPLETED",
         "reason": "The upload appears to contain transactions (id ameio-1234567) that have already been added to Salv. Please make sure that your upload does not contain any duplicates or transactions that have already been added to Salv. The first transaction not added to Salv with this upload has id fmeio-1234567. Last processed and saved row was with id: dseio-1234567"
     }
     

3. In order to check the status of the file upload either use get status of data upload API call or check Data upload page on app.salv.com. This will provide the status and any further information about the errors.

This section contains all operations managing the state of persons and transactions.

There are three endpoints for creating or modifying a person, make sure to choose the right one for your task:

• Create new person will create a new person if a person with the same ID does not already exist in our system.
• Patch person partially updates an existing person if this person exists in the system. A request to this endpoint will only update or add attributes which are provided in the request. Use this endpoint to update selected attributes of a person or to add new attributes without changing attributes not present in the request payload. This endpoint may also be used to update person type.
• Update person updates an existing person if this person exists in the system. A request to this endpoint must contain both person type and attributes. A request to this endpoint overwrites both person type and attributes with the values given in the request.

ID of a person or a transaction is a case-sensitive text field in our system. Salv does not transform the ID in any way. Only the following characters are allowed: Alphanumerics a-zA-Z0-9, hyphens -, underscores _, colons :, dots ..

All requests must use ISO-8601 formatted timestamps. That includes defined fields (e.g. timestamp property in "Create new transaction" request) and custom key-value pairs (e.g. under attributes property in "Create new person" request).

For any data passed in person or transaction objects, the keys must adhere to the following rules:

• It must not contain a "."
• It must not consist of whitespaces

This example shows how to upload data to use it later for monitoring or screening.

1. Add a person if not already added

Add a new person, according to the documentation at addPerson(POST).

If the person has already been added to Salv, then skip this step.

With cURL

curl --request POST \
  --url https://app.salv.com/api/v2/persons \
  --header 'Authorization: Bearer {yourBearerToken}' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "bbt12345",
  "type": "INDIVIDUAL",
  "attributes": {
    "first_name": "Sheldon",
    "last_name": "Cooper",
    "dob": "1983-05-12",
    "city": "Pasadena",
    "street_address": "2311 North Los Robles Avenue",
    "country": "US",
    "onboarding_date": "2019-04-16",
    "email": "[email protected]",
    "phone_number": "+1582693582",
    "id_document": "passport",
    "id_country": "US",
    "gender": "F"
  }
}'

With Python Requests

import requests

url = "https://app.salv.com/api/v2/persons"

payload = {
    "id": "bbt12345",
    "type": "INDIVIDUAL",
    "attributes": {
        "first_name": "Sheldon",
        "last_name": "Cooper",
        "dob": "1983-05-12",
        "city": "Pasadena",
        "street_address": "2311 North Los Robles Avenue",
        "country": "US",
        "onboarding_date": "2019-04-16",
        "email": "[email protected]",
        "phone_number": "+1582693582",
        "id_document": "passport",
        "id_country": "US",
        "gender": "F"
    }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "{yourBearerToken}"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

2. Add a transaction

Add a new transaction, according to the documentation at addTransaction(POST).

With cURL

curl --request POST \
  --url https://app.salv.com/api/v1/persons/bbt12345/transactions \
  --header 'Authorization: Bearer {yourBearerToken}' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "aeio-1234567",
  "attributes": {
    "sender_name": "Sheldon Cooper",
    "sender_account": "GB123456789",
    "receiver_name": "Leonard Hofstadter",
    "receiver_account": "DE987654321",
    "amount": "15678.34",
    "type": "wire_transfer",
    "direction": "I",
    "timestamp": "2022-01-20T08:48:39.000Z"
  }
}'

With Python Requests

import requests

url = "https://app.salv.com/api/v1/persons/bbt12345/transactions"

payload = {
    "id": "aeio-1234567",
    "attributes": {
        "sender_name": "Sheldon Cooper",
        "sender_account": "GB123456789",
        "receiver_name": "Leonard Hofstadter",
        "receiver_account": "DE987654321",
        "amount": "15678.34",
        "type": "wire_transfer",
        "direction": "I",
        "timestamp": "2022-01-20T08:48:39.000Z"
    }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "{yourBearerToken}"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Setting up

You can set up webhook configuration on the webhooks page.

Please note that you must have an administrator role.

Webhook retry mechanism

If sending the webhook fails, we'll retry sending it until it is accepted. Retry attempts happen regularly for up to 7 days, at increasing time intervals:

• 2 minutes
• 5 minutes
• 10 minutes
• 15 minutes
• 30 minutes
• 1 hour
• 2 hours
• 4 hours

After that, retries happen every 8 hours for the following 7 days. For tackling transient errors (like a momentary network glitch) we retry every request 3 times with 1 second interval.

The timeout limit for webhooks is 1 second for connect and 9 seconds for read timeout.

Webhook triggers

Salv supports sending out certain webhooks based on the following event triggers:

• Trigger -> Supported Actions
• ALERT -> ALERT_CREATED
• ALERT_STATUS -> ALERT_STATUS_UPDATED
• SCREENING_ALERT -> SCREENING_ALERT_CREATED
• SCREENING_ALERT_STATUS -> SCREENING_ALERT_STATUS_UPDATED
• FINAL_RISK -> FINAL_RISK_UPDATED
• PERSON_STATUS -> PERSON_STATUS_UPDATED
• PERSON -> The name of the succeeding decision rule. Example: PERSON_CLEARED
• TRANSACTION -> The name of the succeeding decision rule. Example: TRANSACTION_CLEARED
• CUSTOM_LIST_RECORD -> CUSTOM_LIST_RECORD_CREATED, CUSTOM_LIST_RECORD_UPDATED, CUSTOM_LIST_RECORD_ARCHIVED

Decision webhook

When configuring decision webhook rules, every time an alert related to a person or a transaction is changed, this set of rules will be run on all the related alerts for that person/transaction.
If any of the rules succeeds, it will send out a webhook with the name of that rule in action parameter. For more information, check Salv user manual.

Endpoints to add, update, delete and get custom list records.

Custom Lists can be used in two ways:

• Custom Lists can be used to screen persons and transactions against them in the same way it works for Dow Jones lists. For example, if a client has some in-house black list, it can be added to screening as custom list.
• Custom Lists can be referenced in monitoring scenarios. For example, a scenario may trigger when the transaction amount is higher than some threshold and the recipient country is in custom list of high risk countries.

Monitoring allows clients to run various checks (called scenarios) against their persons and transactions. There are three scenario types:

• Real-time (ONLINE) scenarios are run by client by calling real-time checks endpoints. Those are intended to be used for the real time checks, for example to decide whether or not to suspend a transaction.
• Post-event (OFFLINE) scenarios are run by Salv. Person post-event scenarios are run when person is created or updated, transaction post-event scenarios are only run on transaction creation.
• Periodic scenarios are run by Salv according to specified schedule.

All those scenarios are configured in Salv UI. For each pair of triggered scenario and person/transaction one monitoring alert is created. Those alerts are stored by Salv and can later be accessed in UI or by API.

Example: Real-time (pre-processing) transaction monitoring

Transaction monitoring runs all real-time (ONLINE) monitoring scenarios and returns response in realtime. This flow can be used to block a transaction based on transaction monitoring checks.

1. Add a person (if not already added) and a transaction

Add a person and a transaction as shown in Example: Uploading person and transaction.

2. Perform monitoring check

Perform transaction monitoring according to the documentation at runTransactionMonitoringChecks(POST).

With cURL

curl --request POST \
  --url https://app.salv.com/api/v1/transactions/transactionId/monitoring-checks \
  --header 'Authorization: Bearer {yourBearerToken}' \
  --header 'Content-Type: application/json'

With Python Requests

import requests

url = "https://app.salv.com/api/v1/transactions/transactionId/monitoring-checks"

headers = {
    "Content-Type": "application/json",
    "Authorization": "{yourBearerToken}"
}

response = requests.request("POST", url, headers=headers)

print(response.text)

API response when an alert was created

In this case you should block the transaction using your internal logic.

{
  "results": [
    {
      "reason": "High incoming sum",
      "details": "Sum >= 5 000€ (Sum: 19 694.05) in last 30 days",
      "score": 100,
      "weight": 1,
      "scenarioType": "ONLINE",
      "alertId": 321
    },
    {
      "reason": "Outgoing transfer is 80% of the total balance",
      "details": "Amount: 7785.0, balance: 9693.43",
      "score": 100,
      "weight": 1,
      "scenarioType": "ONLINE",
      "alertId": 543
    }
  ]
}

API response when no alert was created

In this case you should process the transaction as no alert was created.

{
  "results": []
}

Decision lifecycle

Transaction monitoring runs all real-time (ONLINE) monitoring scenarios and returns response in realtime. This flow can be used to block a transaction based on transaction monitoring checks.

1. Add a person (if not already added) and a transaction

Add a person and a transaction as shown in Example: Uploading person and transaction.

2. Perform monitoring check

Perform transaction monitoring according to the documentation at runTransactionMonitoringChecks(POST).

With cURL

curl --request POST \
  --url https://app.salv.com/api/v1/transactions/transactionId/monitoring-checks \
  --header 'Authorization: Bearer {yourBearerToken}' \
  --header 'Content-Type: application/json'

With Python Requests

import requests

url = "https://app.salv.com/api/v1/transactions/transactionId/monitoring-checks"

headers = {
    "Content-Type": "application/json",
    "Authorization": "{yourBearerToken}"
}

response = requests.request("POST", url, headers=headers)

print(response.text)

API response when an alert was created

In this case you should block the transaction using your internal logic.

{
  "results": [
    {
      "reason": "High incoming sum",
      "details": "Sum >= 5 000€ (Sum: 19 694.05) in last 30 days",
      "score": 100,
      "weight": 1,
      "scenarioType": "ONLINE",
      "alertId": 321
    },
    {
      "reason": "Outgoing transfer is 80% of the total balance",
      "details": "Amount: 7785.0, balance: 9693.43",
      "score": 100,
      "weight": 1,
      "scenarioType": "ONLINE",
      "alertId": 543
    }
  ]
}

API response when no alert was created

In this case you should process the transaction as no alert was created.

{
  "results": []
}

Person & Transaction monitoring.

Real-time (ONLINE) scenarios should be used when an alert created by the scenario should block the transaction. Example: Real-time (pre-processing) transaction monitoring

Post-event (OFFLINE) scenarios should be used when an alert created should NOT block the transaction. Example: Simple integration

In the rare occasion that a monitoring check fails with error code 500, the transaction should be blocked. In that case Salv has not been able to verify that the transaction is safe to process.

Screening allows clients to check their persons and transactions against screening lists, such as sanctions lists, PEPs (politically exposed persons) lists and adverse media lists. It is also possible to configure custom lists to check persons and transactions against them as well.

There are two ways to use screening.

• To quickly check some name against the screening lists without uploading any data or creating alerts use screening search endpoint.

• To configure more intricate checks first upload person and transaction data to Salv. That will enable automatic person re-screening and allow you to configure a lot of screening details. Then it will be possible to run screening with all that configuration for any particular person or transaction using the API.

Screening settings that can be configured in Salv IU

• Clearance rules
• Fields to screen
• Significant Update Indicators
• Transaction Goodlist Identifiers
• Person and Transaction Segments
• Automatic Re-screening
• Dow Jones lists to screen against
• Custom Lists to screen against
• Fuzzy matching threshold
• BIC Length Threshold

Transaction screening checks transaction sender and recipient names against screening lists

1. Add a transaction

Add a new transaction, according to the documentation at addTransaction(POST).