API documentation: AML Scanner

Version 1.0

Authorization

Authorization to the API of the AML Scanner module is done using the API Key sent in the request header called HFAPIKEY.

The generated key must have the status Active and have access to the AML Scanner module enabled.

Correct API Key configuration for AML Scanner

Details on API key configuration process are available in the HyperFlow Service Platform user documentation chapter 9. API keys.

Language selection

To change a response language please use the HTTP Header called HFLANG in each request.  Supported values are:

• EN – for English language
• PL – for Polish  language

Available API commands

Single search query – AML Scanner for companies

Command	Single query – verification of the company or organization by Polish VAT number or VAT EU number.
HTTP method	POST
URI	https://hyperflow.eu/api/route/amlcheck
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	aml – Polish VAT number or VAT UE number type -”company”

Request example:

{
"aml":"67XXXXX517",
"type":"company"
}

Response example:

{
   "respGus": {
       "companyName": "Jan Kowalski XXX SERWIS",
       "vatno": "67XXXXX517",
       "legalFormType": "Natural Person",
       "legalForm": "Jednoosobowa Działalność Gospodarcza",
       "address": "ul. XXX",
       "city": "Kraków",
       "postCode": "XX-XXX",
       "country": "PL",
       "countryName": "Polska",
       "startUp": "1994-02-08",
       "suspension": "",
       "resumption": "",
       "termination": "",
       "statusREGON": "Active",
       "stat": "A",
       "dateREGON": "2020-08-17",
       "regon": "35XXXXX48",
       "companyNo": "35XXXXX48",
       "email": "",
       "krs": ""
   },
   "respVat": {
       "nip": "67XXXXX517",
       "requestDate": "2020-08-17",
       "resultVat": "ok",
       "vatApiRequestId": "9fbhi-88fajja",
       "name": "JAN KOWALSKI",
       "vatStatus": "Active",
       "vats": "C",
       "vatFrom": "1999-12-21",
       "vatBankAccounts": [
           "11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX859"
       ]
   },
   "respVies": {
       "countryCode": "PL",
       "vatNumber": "67XXXXX517",
       "requestDate": "2020-08-17",
       "valid": true,
       "name": "JAN KOWALSKI",
       "address": "XXXX; XX-XXX KRAKÓW",
       "viesStatus": "Active",
       "viess": "A",
       "resultVies": "ok"
   },
   "nipStatus": "needsAttention",
   "persons": [
       {
           "name": "Jan Kowalski",
           "respSls": {
               "items": [
                   {
                       "name": "Jan Kowalski",
                       "slsResponse": "Not listed on sanctions lists",
                       "isSanctioned": "F"
                   }
               ]
           },
           "respPep": {
               "items": [
                   {
                       "name": "Jan Kowalski",
                       "isPEP": "T",
                       "secondName": "Edmund",
                       "position": [
                           "General directors in supreme offices and central state organs"
                       ],
                       "bornCity": "",
                       "category": [
                           "P9"
                       ],
                       "country": "PL",
                       "countryName": "Poland",
                       "pepRes": "Yes, this person is a PEP"
                   }
               ],
               "consumeId": "10296",
               "result": "ok"
           }
       }
   ],
   "respSls": {
       "items": [
           {
               "name": "Jan Kowalski XXXX SERWIS",
               "slsResponse": "Not listed on sanctions lists",
               "isSanctioned": "F"
           }
       ]
   },
   "companyName": "Jan Kowalski XXXX SERWIS",
   "peopleQuantity": 1,
   "vatno": "67XXXXX517",
   "type": "company",
   "consumeId": "10296",
   "result": "ok"
}

Single search query – AML Scanner for natural persons

Command	Single search for natural persons
HTTP method	POST
URI	https://hyperflow.eu/api/route/amlcheck
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	aml – first and last nametype -”person”

Request example:

{
"aml":"Jan Kowalski",
"type":"person"
}

Response example:

{
   "nipStatus": "needsAttention",
   "persons": [
       {
           "name": "Jan Kowalski",
           "respSls": {
               "items": [
                   {
                       "name": "Jan Kowalski",
                       "slsResponse": "Not listed on sanctions lists",
                       "isSanctioned": "F"
                   }
               ]
           },
           "respPep": {
               "items": [
                   {
                       "name": "Jan Kowalski",
                       "isPEP": "T",
                       "secondName": "Edmund",
                       "position": [
                           "General directors in supreme offices and central state organs"
                       ],
                       "bornCity": "",
                       "category": [
                           "P9"
                       ],
                       "country": "PL",
                       "countryName": "Poland",
                       "pepRes": "Yes, this person is a PEP"
                   }
               ],
               "consumeId": "10300",
               "result": "ok"
           },
           "personId": 0
       }
   ],
   "type": "person",
   "consumeId": "10300",
   "result": "ok"
}

Implementations Notes:

The aml parameter is:

• Name and surname – one string of characters (string) separated by spaces,
• Tax identification number – one string, “-” characters and spaces are removed.

Batch query – Batch Screening AML

Command	Batch query – mass data entry and analysis run
HTTP method	POST
URI	https://hyperflow.eu/api/route/amlbatch
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	“batch”:[”VAT no”,”first and last name”,”VAT no”]

Request example:

{
    "batch":["Abdul Karim",”Islamic Group","Jan Kowalski"]
}

Response example:

{
   "result": "ok",
   "msg": "Scanner running"
}

Implementations Notes:

The batch parameter takes a comma separated array of strings (JSONArray). Each string is constructed according to exactly the same rules as a single aml parameter. This method enters the data into the analysis and runs it. Ending the process does not mean the end of the analysis.

Query from a remote file (own server source or Google Sheets) 

Command	Query from a remote CSV file – Used to check whole set of persons or/and companies that are saved in remote CSV File
HTTP method	POST
URI	https://hyperflow.eu/api/route/amlbatch
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	“hfFile”: {    “name”: “your_file.csv”,    “tmp_name”: “https://remotelocation.com/your_file.csv”}

Request example:

{
  "hfFile": {
 "name": "your_file.csv",
 "tmp_name": "https://remotelocation.com/your_file.csv”
  }
}

Where the file contents look like this:

Batch query – get analysis statistics

Command	Batch query – returns analysis statistics for the entered data
HTTP method	GET
URI	https://hyperflow.eu/api/route/amlbatch/statistics
Request format	JSON
Response format	JSON
Character encoding	UTF-8

Response example:

{
    "pending": 1,
    "error": false,
    "total": 9,
    "statistics": [
        {
            "statusType": "safe",
            "size": 4,
            "quantity": "7",
            "desc": "Safe"
        },
        {
            "statusType": "unknown",
            "size": 4,
            "quantity": "1",
            "desc": "Unknown"
        },
         {
            "statusType": "pending",
            "size": 4,
            "quantity": "1",
            "desc": "Pending"
        }
    ],
    "result": "ok"
}

Implementations Notes:

The query returns statistics from the performed analysis. If the analysis was completed successfully, “pending”: 0.

Batch query – analysis result by status

Command	Batch query – returns analysis results by status
HTTP method	POST
URI	https://hyperflow.eu/api/route/amlbatch/status
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	“status”:[“pending”,”safe”,”needsAttention”]

Request example:

{
    "status":["needsAttention"]
}

Response example:

{
   "report": [
       {
           "date": "2020-08-17",
           "aml": "Islamic Group",
           "type": "person",
           "consumeId": "10334",
           "status": "Needs attention"
       },
       {
           "date": "2020-08-17",
           "aml": "Jan Kowalski",
           "type": "person",
           "consumeId": "10335",
           "status": "Needs attention"
       },
       {
           "date": "2020-08-17",
           "aml": "Abdul Karim",
           "type": "person",
           "consumeId": "10333",
           "status": "Needs attention"
       }
   ],
   "result": "ok"
}

Implementations Notes:

Sending a query with an empty parameter: “status”: [] or “status”: “”, or without this parameter, returns a report of all performed analysis.

Batch query – resuming analysis

Command	Batch query – Resuming an interrupted analysis due to lack of access to the service or other errors
HTTP method	GET
URI	https://hyperflow.eu/api/route/amlbatch/resume
Request format	JSON
Response format	JSON
Character encoding	UTF-8

Response example:

{
   "result": "ok",
   "msg": "Scanner running"
}

Batch query – clear analysis buffer

Command	Batch query – deletes previous analysis records
HTTP method	GET
URI	https://hyperflow.eu/api/route/amlbatch/emptyBuffer
Request format	JSON
Response format	JSON
Character encoding	UTF-8

Response example:

{
   "result": "ok",
   "msg": "The data has been deleted"
}

Implementations Notes:

The command deletes all records entered to analysis.

Query – verification log

Command	Query – returns the result of the last 100 queries, both single and group
HTTP method	GET
URI	https://hyperflow.eu/api/route/amlhistory
Request format	JSON
Response format	JSON
Character encoding	UTF-8

Response example:

{
   "report": [
       {
           "date": "2020-08-17",
           "company": "",
           "consumeId": "10338",
           "sls": "bg-success",
           "pep": "bg-danger",
           "slsStatus": "Not listed on sanctions lists",
           "pepStatus": "Yes, this person is a PEP",
           "person": "Jan Kowalski"
       },
       {
           "date": "2020-08-17",
           "company": "",
           "consumeId": "10336",
           "sls": "bg-danger",
           "pep": "bg-success",
           "slsStatus": "Listed on sanctions lists",
           "pepStatus": "No, this person is not a PEP ",
           "person": "Abdul Karim"
       },
       {
           "date": "2020-08-17",
           "company": "",
           "consumeId": "10337",
           "sls": "bg-danger",
           "pep": "bg-success",
           "slsStatus": "Listed on sanctions lists",
           "pepStatus": "No, this person is not a PEP ",
           "person": "Islamic Group"
       }
   ],
   "result": "ok"
}

Implementations Notes:

Each record contains data about a company and / or person. If the record contains both the non-empty “company” parameter and the “person” parameter, it means that the person is related to the given company as UBO. In this case, the verification of the company and the person contains the same “consumeId”.

Query – search verification log by date or content of the query

Command	The query returns the results of the analysis by date or containing the data entered in the query body
HTTP method	POST
URI	https://hyperflow.eu/api/route/amlhistory/find
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	“query”:”2020-08-14”

Request example:

{
    "query":"Karim"
}

Response example:

{
   "report": [
       {
           "date": "2020-08-17",
           "company": "",
           "consumeId": "10336",
           "sls": "bg-danger",
           "pep": "bg-success",
           "slsStatus": "Listed on sanctions lists",
           "pepStatus": "No, this person is not a PEP ",
           "person": "Abdul Karim"
       }
   ],
   "result": "ok"
}

Implementations Notes:

Parameters: “isSanctioned” and “isPEP” are parameters that define the status on sanctions lists / PEP lists and take three values:

“U” – undefined,
“T” – true – is on sanctions lists / is PEP,
“F” – false – is not on sanctions lists / is not PEP,

Query recommendations

The recommended way to query the API is to provide the first and last name, tax identification number or EU VAT number of the organization/company. In case of an ambiguous answer – when the “hit” affects more than one person / company – all results will be returned.

In the case of positive verification (is on the sanctions lists / is PEP), all available information about the person / company and the sanctions imposed are returned each time (in the case of a person, it is possible date of birth or year of birth, possible names used; in the case of a company / organization: possible names used; all responses contain the type of sanctions list and its reference number).

Using example with the RESTED client

Error Codes

Error:

{
  "code": "0089",
  "redirect": "",
  "result": "err",
  "msg": "No access to this service"
}

Cases:

• The user has used up the entire pool of purchased queries or the date by which the service has been purchased has expired,
• Inactive API key,
• The API key does not have AML Scanner service enabled.

Error:

{
  "code": "0404",
  "redirect": "",
  "result": "err",
  "msg": "No file or file is empty"
}

Cases:

• The path provided is not valid,
• The file contains no data, is empty,
• Incorrect file format, the file is not a CSV file,
• Incorrectly entered parameter names: “name”, “tmp_name”.

Error:

{
   "code": "0448",
   "redirect": "",
   "result": "err",
   "msg": "No entity type"
}

Cases:

• Incorrectly entered parameter name: “type”,
• “type” parameter is empty or its value is different than “company” or “person”,
• No parameter “type” in the request.

Error:

{
   "code": "0445",
   "redirect": "",
   "result": "err",
   "msg": "Empty data"
}

Cases:

• Incorrectly entered parameter name: “aml”, 
• “aml” parameter is empty,
• No parameter “aml” in the request.

Error:

{
   "code": "0333",
   "redirect": "",
   "result": "err",
   "msg": "Bad country id"
}

Cases:

• The entered EU VAT number has an incorrect country identifier (e.g. GF1232343445 – GF there is no country with such a code).

Error:

{
   "code": "0000",
   "redirect": "",
   "result": "err",
   "msg": "Unknown command"
}

Cases:

• Incorrect URI,
• The selected method is not valid for the query (POST / GET).