Argos natural person API

1. Introduction

Argos Natural Person is an artificial intelligence service designed to analyze and interpret global person-related data and generate structured risk analysis reports.

The service processes large volumes of data from international risk watchlists and provides: • PEP (Politically Exposed Persons) match analysis • International sanctions detection (OFAC, UN, EU) • Adverse media identification • Regulatory enforcement action assessment • Automated risk level classification • Generation of professional PDF reports

Use cases

  1. Customer Onboarding Risk Assessment Financial institutions can automatically analyze new customer data against international watchlists to identify PEP status, sanctions exposure, and adverse media, enabling faster and compliant onboarding decisions.
  2. Ongoing Customer Monitoring The service continuously evaluates existing clients against updated risk databases, detecting new sanctions, regulatory actions, or reputational risks in near real-time.
  3. Third-Party / Vendor Due Diligence Organizations can assess suppliers, partners, and contractors by analyzing their exposure to sanctions, enforcement actions, or negative media before establishing business relationships.
  4. Compliance Automation for AML Programs Compliance teams can streamline Anti-Money Laundering (AML) workflows by automating risk classification and generating structured reports for audits and regulatory reviews.
  5. Enhanced Due Diligence (EDD) For high-risk entities or individuals, the service provides deeper analysis, consolidating risk indicators into detailed reports that support decision-making processes.
  6. Regulatory Reporting and Audit Support Automatically generated PDF reports provide traceability and documentation required for regulatory audits and internal compliance reviews.

2. General information

URLs of the service

Resource URL
Base URL https://web-prod01.tuidentidad.com
Swagger UI https://web-prod01.tuidentidad.com/api/argos/physicalPerson

Technical Specifications

Specification Value
Protocolo HTTP/HTTPS
Data format JSON
Method HTTP POST
Authentication API Key (Header)
Content-Type application/json
Supported languages Spanish (es), English (en)

3. Authentication

Each company is assigned a unique, non-transferable API key that must be included to authenticate requests.

Headers

Header Type Required Description
ApiKey string yes Customer key.

Example: ApiKey: YOUR_API_KEY

Authentication Errors

Code Error Description
401 AUTH001 API key missing from the header
402 AUTH002 API key is invalid or not authorized.

Example JSON response when no API key is provided

{
 "success": false,
 "analysis_result": null,
 "warnings": [{
 "code": "AUTH001",
 "message": "API Key is missing",
 "fullMessage": "API Key is required. Please provide it in the  
header."
 }]
}

4. Endpoint: /interpreter

Propertie Value
URL https://web-prod01.tuidentidad.com/api/argos/physicalPerson
Method POST
Content-Type application/json
Authentication Required (ApiKey)

5. Request Format

Headers

Header Type Required Description
ApiKey string yes Customer key.

Body Parameters

field Type Required Description
json object yes BGC media service JSON response.
names string yes Names of the person to search for.
lastName string yes Last name of the person.
secondLastName string No Second lastname of the person.
birthDate string No Birth date of the person. Format (MM/DD/YYYY).
country string No Country code. ISO 3166 alpha-2. Example: (MX, US).
lang string No Language: "en" (english), "es" (spanish). Default value: "en"

Example Request

POST /interpreter HTTP/1.1
Host: https://web-prod01.tuidentidad.com/api/argos/physicalPerson
Content-Type: application/json
ApiKey: YOUR_API_KEY

{
 "json": {
   "records": [...],
   "warnings": null
  },
  "names": "Juan Daniel",
  "lastName": "Flores",
  "secondLastName": "Montes",
  "dateBirth": "01/15/1985",
  "country": "MX",
  "lang": "es"
}

6. Response Format

Structure

Field Type Description
success boolean Specifies whether the operation succeeded.
analysis_result object Result of the analysis (null if an error occurs).
warnings array List of warnings or errors encountered during the operation.

analysis_result object

Field Type Description
analyzedName string Full name analyzed.
risk string Level risk: Critical, High, Medium, Low.
pep boolean Specifies whether the individual qualifies as a Politically Exposed Person (PEP).
pepActive boolean Indicates whether the PEP role is active.
pepHistory array PEP history record.
position string Job position.
country string Country
startDate string Start date of the job position
endDate string End date of the job position
personalInfo object Personal data of the person.
fullName string Full name of the person.
dateOfBirth string Birth date of the person.
country string Country abbreviation
entityType string Entity type
relevantData object Key analysis data.
totalMatches integer Total of matches found.
listsFound array Name of the found lists.
riskCategories array Categories of risk.
pep boolean If the person is a Politically Exposed Persons.
sanctions boolean If the person have sanctions.
adverseMedia boolean If the person is in adverse media.
enforcement boolean Enforcement.
conclusion string Executive summary of the analysis.
sources array Sources consulted.
listName string Name of the list.
publicationDate string Date of publication.
listType string List type.
reference string Reference
file string Base64-encoded PDF report.
warnings array List of warnings.

Level of risk

Level of risk Criterial
Critical Active sanctions, major adverse media (terrorism, drug trafficking), verified criminal organizations.
High Active PEP in a high-risk jurisdiction, recent enforcement actions, state-owned enterprise (SOE) under an authoritarian government.
Medium Inactive PEP, PEP relatives, low-severity adverse media, honorary/ceremonial roles.
Low Homonyms with low scores ( < 70 ), auto false positives, no real matches.

Example of successful response

{
    "success": true,
    "analysisResult": {
        "analyzedName": "Lionel Andrés Messi Cuccittini",
        "risk": "Medium",
        "pep": true,
        "pepActive": false,
        "pepHistory": [
            {
                "position": "Embajador de Buena Voluntad de UNESCO",
                "country": "Internacional",
                "startDate": null,
                "endDate": null
            }
        ],
        "personalInfo": {
            "fullName": "Lionel Andrés Messi Cuccittini",
            "dateOfBirth": "06/24/1987",
            "country": "AR",
            "entityType": "Individual"
        },
        "relevantData": {
            "totalMatches": 1,
            "listsFound": [
                "PEP"
            ],
            "riskCategories": [
                "PEP"
            ],
            "pep": true,
            "sanctions": false,
            "adverseMedia": false,
            "enforcement": false
        },
        "conclusion": "El análisis identifica a Lionel Andrés Messi Cuccittini como titular de un cargo diplomático honorario como Embajador de Buena Voluntad de UNESCO, lo cual lo clasifica como PEP según definiciones regulatorias. Sin embargo, este es un rol ceremonial sin autoridad política directa ni poder de decisión gubernamental. El sujeto es principalmente conocido como futbolista profesional en lugar de figura política. Dada la naturaleza honoraria del nombramiento diplomático y la falta de participación gubernamental activa, se asigna una calificación de riesgo Medio para fines de monitoreo de cumplimiento.",
        "sources": [
            {
                "listName": "PEP",
                "publicationDate": null,
                "listType": "PEP",
                "reference": null
            }
        ],
        "file": "JVBER="
    },
    "warnings": []
}

7. Error codes

Code Message FullMessage Description
AUTH001 API Key was not provided. API Key was not provided. API Key was not provided.
AUTH002 API key is invalid or not authorized. API key is invalid or not authorized. Message displayed when the provided ApiKey is invalid or not autorized.
INTER001 Unexpected error occurred An unexpected error has occurred. Please try again later. An internal error of the analysis service.
INTER002 JSON is missing to be analyzed The JSON file for parsing is required in the request. The 'json' field is required.
INTER003 Name is missing to be analyzed The name is required in the request. The 'names' field is required.
INTER004 Last name is missing to be analyzed The last name is required in the request. The 'lastName' field is required.
INTER005 Format incorrect for birthDate The birthdate does not comply with the MM/DD/YYYY format. The format of the date is invalid (MM/DD/YYYY)
INTER006 Format incorrect for country country does not comply with the ISO 3166-1 alpha-2 format. The country code is invalid.
INTER007 The language is not supported The language specified is not supported, please use 'en' for English or 'es' for Spanish Not supported language (please use "en" or "es")
INTER008 JSON structure is invalid The provided JSON is malformed or contains invalid syntax. Please verify the structure. An error occurred while processing the JSON.
INTER010 JSON size exceeds limit The provided JSON exceeds the maximum allowed size of 5MB. The JSON is larger than the maximum allowed size.
INTER011 InterpreterIA API connection failed Unable to connect to InterpreterIA API. Please check your connection and try again. An error occurred, the InterpreterIA API connection failed.
INTER012 Invalid or expired API key The InterpreterIA API key is invalid or has expired. Please contact support. The InterpreterIA API key is invalid or has expired.
INTER013 Token limit exceeded The analysis exceeded the maximum allowed tokens. Please reduce the JSON size or split the request. Maximum token limit exceeded.
INTER014 Processing timeout The analysis exceeded the maximum processing time. Please try again or reduce the data size. The analysis exceeded maximum processing time.
INTER015 PDF generation failed Unable to generate the PDF report. The analysis result is available but the PDF could not be created. Error generating the PDF (analysis completed).

Structure in case of error

{
 "success": false,
 "analysis_result": null,
 "warnings": [
   {
     "code": "INTER003",
     "message": "Field 'names' is required",
     "fullMessage": "The 'names' field is required and cannot be empty."
   }
 ]
}

8. Examples of integration

CURL

curl -X POST "https://web-prod01.tuidentidad.com/api/argos/physicalPerson" \
  -H "Content-Type: application/json" \
  -H "ApiKey: YOUR_API_KEY" \
  -d '{
    "json": {"records": [...], "warnings": null},
    "names": "Juan Daniel",
    "lastName": "Flores",
    "lang": "es"
  }'

Python (request)

import requests
import base64

url = "https://web-prod01.tuidentidad.com/api/argos/physicalPerson"
headers = {
    "Content-Type": "application/json",
    "ApiKey": "YOUR_API_KEY
}

payload = {
    "json": bgc_media_response,  # Response of BGC Media
    "names": "Juan Daniel",
    "lastName": "Flores",
    "secondLastName": "Montes",
    "dateBirth": "1985-01-15",  # The recommended format YYYY-MM-DD
    "country": "MX",
    "lang": "es"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data.get("success"):
    # Save PDF
    pdf_base64 = data["analysis_result"]["file"]
    pdf_bytes = base64.b64decode(pdf_base64)
    with open("reporte.pdf", "wb") as f:
        f.write(pdf_bytes)
    print(f"Riesgo: {data['analysis_result']['risk']}")
else:
    print(f"Error: {data['warnings'][0]['fullMessage']}")

JavaScript (fetch)

const response = await fetch(
  "https://web-prod01.tuidentidad.com/api/argos/physicalPerson",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "ApiKey": "YOUR_API_KEY"
    },
    body: JSON.stringify({
      json: bgcMediaResponse,
      names: "Juan Daniel",
      lastName: "Flores",
      lang: "es"
    })
  }
);

const data = await response.json();

if (data.success) {
  // Download PDF
  const pdfBase64 = data.analysis_result.file;
  const link = document.createElement("a");
  link.href = "data:application/pdf;base64," + pdfBase64;
  link.download = "reporte.pdf";
  link.click();

  console.log("Riesgo:", data.analysis_result.risk);
} else {
  console.error("Error:", data.warnings[0].fullMessage);
}

C Sharp (.NET)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("ApiKey", "YOUR_API_KEY");

var payload = new
{
    json = bgcMediaResponse,
    names = "Juan Daniel",
    lastName = "Flores",
    lang = "es"
};

var response = await client.PostAsJsonAsync(
    "https://web-prod01.tuidentidad.com/api/argos/physicalPerson",
    payload
);

var data = await response.Content.ReadFromJsonAsync<ApiResponse>();

if (data.Success)
{ 
    var pdfBytes = Convert.FromBase64String(data.AnalysisResult.File);
    await File.WriteAllBytesAsync("reporte.pdf", pdfBytes);}
{

Best practices

Security

  1. Never expose your API key in client-side code.
  2. Store API keys in environment variables or secret management services.
  3. Use HTTPS in production.
  4. Rotate your API keys periodically.

10. Support

For technical support or integration inquiries, please contact us through the following channels.

Channel Contact
Web site https://tuidentidad.com
Documentation https://web-prod01.tuidentidad.com/api/argos/physicalPerson
Email support soporte@tuidentidad.com

When reporting an issue, please include the following information:

  • Error code received (e.g., INTER001)
  • Request date and time
  • Request sent
  • Response received
  • Programming language