Skip to main content
POST
/
entities
/
{entityId}
/
analyze
Analyze Entity
curl --request POST \
  --url http://api.gu1.ai/entities/{entityId}/analyze \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityType": "<string>",
  "enrichIfNeeded": true,
  "providerCodes": [
    {}
  ]
}
'
{
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Overview

Manually triggers risk analysis for an entity using the configured risk matrix and rules. Optionally enriches the entity before analysis.

​
Endpoint

POST http://api.gu1.ai/entities/{entityId}/analyze

​
Path Parameters

​
entityId
string
required
UUID of the entity to analyze

​
Request Body

​
entityType
string
required
Entity type: person, company, or transaction
​
enrichIfNeeded
boolean
default:"false"
Whether to run enrichment before analysis
​
providerCodes
array
Specific provider codes to execute for enrichment

​
Example Requests

​
Basic Analysis

curl -X POST http://api.gu1.ai/entities/entity-123/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "person"
  }'

​
Analysis with Enrichment

curl -X POST http://api.gu1.ai/entities/entity-123/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "company",
    "enrichIfNeeded": true
  }'

​
Analysis with Specific Providers

curl -X POST http://api.gu1.ai/entities/entity-123/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "person",
    "providerCodes": [
      "global_complyadvantage_pep_enrichment",
      "global_complyadvantage_sanctions_enrichment"
    ]
  }'

​
Response - Success

The response includes data (analysis details), and when rules ran also rulesResult and rulesExecutionSummary at the root (same as create, enrich, refresh).
​
rulesResult
object
Full rules execution result when analysis ran: success, executed, result, rulesTriggered, executionTimeMs, auditId, isNewAudit, rulesExecutionSummary (same object as root field below).
​
rulesExecutionSummary
object
At the root of the response (same as transactions API). Same value as rulesResult.rulesExecutionSummary. Only present when rules ran. Summary of which rules matched (hit) vs did not (no hit), executed actions, and total score. Structure: rulesHit, rulesNoHit, actionsExecuted, totalScore.
{
  "success": true,
  "data": {
    "id": "audit-789",
    "entityId": "entity-123",
    "entityType": "person",
    "overallRiskScore": 75,
    "riskLevel": "HIGH",
    "rulesTriggered": 3,
    "rulesExecuted": 15,
    "executionTimeMs": 342,
    "riskFactors": [
      {
        "ruleName": "PEP Detection",
        "ruleId": "rule-456",
        "matched": true,
        "score": 35,
        "severity": "HIGH",
        "category": "compliance"
      }
    ],
    "recommendations": [
      "Enhanced due diligence required",
      "Review PEP relationships"
    ],
    "analyzedAt": "2024-12-23T10:00:00Z",
    "metadata": {
      "matrixId": "rm-123",
      "matrixName": "AML Risk Matrix",
      "matrixVersion": 1
    }
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 3,
    "executionTimeMs": 342,
    "auditId": "audit-789",
    "isNewAudit": true,
    "rulesExecutionSummary": { "rulesHit": [], "rulesNoHit": [], "actionsExecuted": {}, "totalScore": 75 }
  },
  "rulesExecutionSummary": { "rulesHit": [], "rulesNoHit": [], "actionsExecuted": {}, "totalScore": 75 }
}

​
Response - No Rules Configured

{
  "success": true,
  "warning": {
    "code": "NO_RULES_FOUND",
    "message": "No active rules found for this entity type"
  },
  "data": {
    "entityId": "entity-123",
    "entityType": "person",
    "rulesTriggered": 0,
    "analyzedAt": "2024-12-23T10:00:00Z"
  }
}

​
Response - Incomplete Data

{
  "success": false,
  "error": {
    "code": "INCOMPLETE_DATA_COVERAGE",
    "message": "Cannot calculate risk score without complete data coverage",
    "details": {
      "missingFields": ["taxId", "dateOfBirth"],
      "recommendedProviders": [
        "br_cpfcnpj_complete_person_enrichment"
      ]
    }
  }
}

​
Risk Levels

  • LOW: 0-29 - Minimal risk
  • MEDIUM: 30-59 - Moderate risk, standard monitoring
  • HIGH: 60-79 - Elevated risk, enhanced monitoring required
  • CRITICAL: 80-100 - Severe risk, immediate action required

​
Use Cases

​
Analyze After Data Update

// Update entity data
await updateEntity(entityId, newData);

// Re-analyze to get updated risk score
const analysis = await fetch(
  `http://api.gu1.ai/entities/${entityId}/analyze`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityType: 'person',
      enrichIfNeeded: true
    })
  }
);

const result = await analysis.json();
console.log(`Risk Score: ${result.data.overallRiskScore}`);

​
Batch Analysis

import asyncio
import aiohttp

async def analyze_entities(entity_ids):
    async with aiohttp.ClientSession() as session:
        tasks = []
        for entity_id in entity_ids:
            task = session.post(
                f'http://api.gu1.ai/entities/{entity_id}/analyze',
                headers={'Authorization': 'Bearer YOUR_API_KEY'},
                json={'entityType': 'company'}
            )
            tasks.append(task)

        results = await asyncio.gather(*tasks)
        return [await r.json() for r in results]

# Analyze multiple entities
entity_ids = ['entity-1', 'entity-2', 'entity-3']
results = asyncio.run(analyze_entities(entity_ids))

for result in results:
    print(f"Entity: {result['data']['entityId']}")
    print(f"Risk Score: {result['data']['overallRiskScore']}")

​
See Also