Service Documentation: "AMLRISK Search"

Welcome to AMLRISK. This application is designed for performing searches on natural or legal persons in globally recognized binding and risk-related lists. This document describes how to consume the REST protocol WebService for mass searches.

Service Overview

• Service Name: AMLRISK Search Service
• URL: https://btrust-api.ado-tech.com/prod/aml
• Method: POST
• Functionality: Allows for mass searches of individuals or entities on globally recognized binding and risk-related lists using a RESTful API. This service accepts JSON objects containing personal or entity identification data and returns matching results from various risk and compliance databases.

Request Parameters

Request Headers

• Content-Type: application/json
• projectName: [Your_Project_Name]
• X-API-Key: [Your_API_Key]

Request Body

You should send a JSON object with the data of the persons you want to query. It's not necessary for all fields to be present, but it is recommended to include both the name and the identification number as they appear on the official document.

• Name: The full name of the individual or entity being searched. Names should be sent in strict order, first names followed by surnames.
• Identification (optional): The identification number as it appears on the official document.
• SearchJudicialBranch (optional): A boolean parameter to indicate whether to include judicial branch sources in the search.
• SearchProcuration (optional): A boolean parameter to indicate whether to include procurator sources in the search.

Request Body Example

{
  "Name": "[Full_Name]",
  "Identification": "[Identification_Number]",
  "SearchJudicialBranch": false,
  "SearchProcuration": false
}

Replace placeholder values (e.g., your_api_key, unique_customer_id, etc.) with actual data relevant to your verification process.

Example CURL Request

curl --location 'https://btrust-api.ado-tech.com/prod/aml' \
--header 'projectName: [Your_Project_Name]' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: [Your_API_Key]' \
--data '{
  "Name": "[Full_Name]",
  "Identification": "[Identification_Number]",
  "SearchtJudicialBranch": false,
  "SearchProcuration": false
}'

Replace placeholder values (e.g., [Full_Name], [Identification_Number], etc.) with actual data relevant to your verification process.

Response Structure for "Create Process" Service

Upon making a request to the "Create Process" service, the server will respond with a status code indicating the outcome of the request. Below are the possible responses you might receive:

Successful Response

Code: 200 Content:

{
  "datetime": "2021-11-25 16:19:50",
  "id_bitacora": 4609695,
  "results": [
    {
      "item_no": 2,
      "nombre": "Miguel Angel Orejuela",
      "doc_id": "98563386",
      "block": true,
      "datos_pro": null,
      "datos_ramajudicial": null,
      "datos_amlnews": [],
      "datos_tsti": [
        {
          "lista": ["5349"],
          "estado": null,
          "categoria": ["Barequeros"],
          "nombre_apellido": ["MIGUEL ANGEL OREJUELA MARTINEZ"],
          "url": "https://tramites.anm.gov.co/Portal/pages/consultaListados/anonimoListados.jsf",
          "pais": ["COLOMBIA"],
          "detalle": ["Registro Único de Comercializadores de Minerales RUCOM, de la Agencia Nacional de Minería contiene la relación de personas naturales y jurídicas registradas como barequeros o comerciantes de Minerales"],
          "id": "1378617",
          "nombre_relacion_lista": ["Agencia Nacional de Minería RUCOM."],
          "id_relacion_lista": ["154"],
          "_version_": 1715704460641042432,
          "estado1": null,
          "estado2": null,
          "estado3": null,
          "relacionado": "[]"
        },
        {
          "lista": ["2776"],
          "estado": null,
          "categoria": ["SDNTK"],
          "nombre_apellido": ["DIAZ OREJUELA, Miguel Angel"],
          "pasaporte2": ["AI481119"],
          "url": "http://bit.ly/1MLgpye ,http://bit.ly/1I7ipyR",
          "detalle": ["Specially Designated Nationals (SDN) - Treasury Department"],
          "pasaporte": ["AI481119"],
          "n_identificacion2": ["17412428"],
          "ciudadania": ["CO"],
          "alias": [""],
          "id": "1726895",
          "n_identificacion": ["17412428"],
          "nombre_relacion_lista": ["BIS"],
          "id_relacion_lista": ["352"],
          "_version_": 1715704497073815552,
          "estado1": null,
          "estado2": null,
          "estado3": null,
          "relacionado": "[]"
        }
      ],
      "datos_twitter": null
    }
  ],
  "elapsed_time": 0.15829205513
}

Description: This response indicates that the process was successfully executed. The API returns a JSON object with the search results. Each object in the results list represents an individual query.

Explanation of the Response Structure

datetime: Timestamp indicating when the response was generated. id_bitacora: A unique log identifier to facilitate search auditing and tracking. results: An array of search result items, each containing:

item_no: The item number in the list of results. nombre: The full name of the individual queried. doc_id: The identification document number. block: Boolean indicating whether the individual is blocked based on the search criteria. datos_pro, datos_ramajudicial, datos_amlnews: Fields for specific data sources (currently null, indicating no data retrieved from these sources). datos_tsti: Array of detailed listings from searched lists, including:

lista: Array of list codes the individual appears on. estado: Current status (null in this case, meaning no specific status reported). categoria: Categories associated with the individual on the lists. nombre_apellido: Array containing full names as they appear on the list. url: URL to more information or the list entry. pais: Country associated with the individual or the listing. detalle: Detailed description of the list entry. id: Unique identifier for the list entry. nombre_relacion_lista: Name of the list the entry is associated with. id_relacion_lista: Identifier for the related list. version: Internal version number for the entry. estado1, estado2, estado3: Additional status fields, if applicable (all null here). relacionado: Related entries or additional data (empty array indicates no related entries). datos_twitter: Field for potential social media data (null here). elapsed_time: The time taken to process the query, in seconds.

Client Error Response

Code: 400 Content:

{
  "Bad Request": "The provided data does not meet the expected criteria."
}

Description: This response is returned when the request fails due to invalid or incomplete data provided by the client. It suggests that the submitted parameters do not align with what the service expects.

Unauthorized Error Response

Code: 401 Content:

{
  "Unauthorized": "Invalid API key or insufficient permissions."
}

Description: This response indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. It is a generic error message, implying that the issue lies with the server rather than the request itself.

Server Error Response

Code: 500 Content:

{
  "Internal Server Error": "An error occurred on the server."
}

Description: This response indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. It is a generic error message, implying that the issue lies with the server rather than the request itself.

Implementation Notes

Source Inclusion: It's important to note that sources such as the Procuraduría, Judicial Branch, and the National Registry are not part of our core engine. When activated, AMLRISK sends query parameters to each source, and the response returned by these sources is stored. Name Order: The names of individuals must be sent in strict order, starting with given names followed by surnames. Log ID Storage: We recommend storing the id_bitacora field in applications that integrate this service. This log ID will facilitate searches in case of audits. Source Availability: If a source is not available at the time of query, the response will indicate which source did not respond, and the other sources will still be processed. Response Time: Response times of the web service may significantly increase when querying external sources (Procuraduría, Judicial Branch, and National Registry). Request Validation: All requests are validated through the AML engine. Security: Ensure the x-api-key is securely stored and transmitted. Error Handling: Implement appropriate error handling to manage potential issues, such as network errors or unauthorized access.

These implementation notes are crucial for understanding the operational scope and limitations of the AMLRISK Search Service, ensuring that users can properly integrate and utilize the service within their systems.