Execute Risk Matrix

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": [
    "<string>"
  ],
  "rulesEngineConfig": {}
}
'

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

entities

{entityId}

analyze

Execute Risk Matrix

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": [
    "<string>"
  ],
  "rulesEngineConfig": {}
}
'

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

Overview

Manually triggers risk matrix analysis for an entity using configured rules. The risk matrix evaluates the entity against all active rules and calculates a risk score. Optionally enriches the entity before analysis. This is the same endpoint used for Analyze Entity, but documented here for convenience when specifically working with risk matrices.

Endpoint

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

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

entityId

string

required

UUID of the entity (company or person) to analyze

Request Body

entityType

string

required

Type of entity to analyze

person - Individual/person entity
company - Company/business entity
transaction - Transaction entity

enrichIfNeeded

boolean

default:"false"

Whether to run data enrichment before analysis. If true, will execute all active enrichment integrations configured for this organization.

providerCodes

array<string>

Specific enrichment provider codes to execute before analysis. Only used when enrichIfNeeded is true. See Provider Codes Reference.

rulesEngineConfig

object

Per-run rules engine behavior. See Analyze Entity — rulesEngineConfig (partialCoverage, omitCoverage; both default false).

Response

success

boolean

Whether the analysis was successful

data

object

Analysis result data:

id (string) - Audit ID for this analysis
entityId (string) - Entity that was analyzed
entityType (string) - Type of entity
overallRiskScore (number) - Overall risk score (0-100)
riskLevel (string) - Risk level: LOW, MEDIUM, HIGH, CRITICAL
confidence (number) - Confidence level of the analysis (0-100)
rulesTriggered (number) - Number of rules that matched
rulesExecuted (number) - Total number of rules evaluated
executionTimeMs (number) - Total execution time in milliseconds
riskFactors (array) - Rules that matched/triggered
recommendations (array) - Recommended actions
analyzedAt (string) - ISO timestamp of analysis
triggeredBy (string) - Who/what triggered the analysis
metadata (object) - Additional metadata including matrix info

rulesResult

object

Full rules execution result when analysis ran: success, executed, result, rulesTriggered, executionTimeMs, auditId, isNewAudit, rulesExecutionSummary (same 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 (includes alerts, suggestion, status, assignedUser, customKeys — array of custom action keys from matched rules, for integrations/workflows), totalScore.

Examples

Basic Risk Matrix Execution

curl -X POST http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "person"
  }'

Execute with Auto-Enrichment

curl -X POST http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "company",
    "enrichIfNeeded": true
  }'

Execute with Specific Enrichments

curl -X POST http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "person",
    "enrichIfNeeded": true,
    "providerCodes": [
      "br_cpfcnpj_complete_person_enrichment",
      "global_complyadvantage_person_search_enrichment"
    ]
  }'

Response Example

Successful Analysis

{
  "success": true,
  "data": {
    "id": "audit_789xyz",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityType": "person",
    "overallRiskScore": 75,
    "riskLevel": "HIGH",
    "confidence": 85,
    "rulesTriggered": 3,
    "rulesExecuted": 15,
    "executionTimeMs": 1250,
    "riskFactors": [
      {
        "ruleId": "rule_pep_detection",
        "ruleName": "PEP Detection",
        "matched": true,
        "score": 35,
        "severity": "HIGH",
        "category": "compliance",
        "priority": 1,
        "description": "Entity identified as politically exposed person",
        "actionsExecuted": [
          {
            "type": "createAlert",
            "details": {
              "title": "PEP Detected",
              "severity": "HIGH"
            }
          },
          {
            "type": "updateEntityStatus",
            "details": {
              "status": "under_review"
            }
          }
        ]
      },
      {
        "ruleId": "rule_high_income",
        "ruleName": "High Income Threshold",
        "matched": true,
        "score": 25,
        "severity": "MEDIUM",
        "category": "financial",
        "priority": 3
      },
      {
        "ruleId": "rule_age_verification",
        "ruleName": "Age Verification",
        "matched": true,
        "score": 15,
        "severity": "LOW",
        "category": "identity",
        "priority": 5
      }
    ],
    "recommendations": [
      "Enhanced due diligence required",
      "Review PEP relationships",
      "Verify source of funds"
    ],
    "analyzedAt": "2024-12-24T10:30:00.000Z",
    "triggeredBy": "manual_evaluation",
    "metadata": {
      "matrixId": "rm_abc123",
      "matrixName": "AML Risk Matrix",
      "matrixVersion": 1,
      "totalRulesEvaluated": 15,
      "rulesMatched": 3,
      "cached": false
    }
  }
}

No Active Rules Warning

{
  "success": true,
  "warning": {
    "code": "NO_RULES_FOUND",
    "message": "No active rules found for this entity type. Please configure rules in the Risk Matrix to enable risk analysis."
  },
  "data": {
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityType": "person",
    "overallRiskScore": 0,
    "rulesTriggered": 0,
    "rulesExecuted": 0,
    "analyzedAt": "2024-12-24T10:30:00.000Z"
  }
}

Incomplete Data Coverage

{
  "success": false,
  "error": {
    "code": "INCOMPLETE_DATA_COVERAGE",
    "message": "Cannot calculate risk score without complete data coverage",
    "details": {
      "missingFields": ["taxId", "dateOfBirth", "nationality"],
      "recommendedProviders": [
        "br_cpfcnpj_complete_person_enrichment"
      ],
      "warnings": [
        "Required field 'taxId' is missing",
        "Required field 'dateOfBirth' is missing"
      ]
    }
  }
}

Risk Levels

The system calculates risk levels based on the overall risk score:

LOW (0-29): Minimal risk, standard processing
MEDIUM (30-59): Moderate risk, standard monitoring required
HIGH (60-79): Elevated risk, enhanced monitoring required
CRITICAL (80-100): Severe risk, immediate action and enhanced due diligence required

Rule Actions

When rules match, they can trigger automatic actions:

createAlert - Creates an alert for manual review
updateEntityStatus - Changes entity status (e.g., to under_review)
addTag - Adds tags to the entity for categorization
sendEmail - Sends email notification
webhook - Triggers webhook for external integration

Error Responses

404 Not Found - Entity Not Found

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity not found"
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "User ID is required"
  }
}

422 Unprocessable Entity - Incomplete Data

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

Real-Time Notifications

When risk matrix execution completes, a real-time notification is sent via WebSocket:

{
  "notificationType": "RISK_MATRIX_EXECUTED",
  "title": "Risk Matrix Executed",
  "message": "Risk analysis completed for entity",
  "severity": "INFO",
  "details": {
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "riskScore": 75,
    "riskLevel": "HIGH",
    "rulesTriggered": 3
  }
}

Best Practices

Enrich First: For best results, enrich entity data before analysis using enrichIfNeeded: true
Handle Warnings: Check for NO_RULES_FOUND warning and configure rules if needed
Data Coverage: Ensure required fields are populated to avoid INCOMPLETE_DATA_COVERAGE errors
Monitor Actions: Review actionsExecuted to understand what automated actions were taken
Caching: Results are cached for performance - use cached field to check if analysis is fresh

Use Cases

Onboarding Risk Assessment

// Enrich and analyze new customer during onboarding
const analysis = await fetch(
  `http://api.gu1.ai/entities/${customerId}/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();

// Make decision based on risk level
if (result.data.riskLevel === 'CRITICAL') {
  await rejectOnboarding(customerId);
} else if (result.data.riskLevel === 'HIGH') {
  await requestManualReview(customerId);
} else {
  await approveOnboarding(customerId);
}

Periodic Re-assessment

import schedule
import time

def reassess_high_value_customers():
    """Periodically re-assess high-value customers"""
    customers = get_high_value_customers()

    for customer in customers:
        response = requests.post(
            f'http://api.gu1.ai/entities/{customer["id"]}/analyze',
            headers={'Authorization': 'Bearer YOUR_API_KEY'},
            json={'entityType': 'person'}
        )

        result = response.json()
        if result['data']['riskLevel'] in ['HIGH', 'CRITICAL']:
            notify_compliance_team(customer['id'], result['data'])

# Run daily at 2 AM
schedule.every().day.at("02:00").do(reassess_high_value_customers)

while True:
    schedule.run_pending()
    time.sleep(60)

Transaction Risk Scoring

// Analyze risk before processing high-value transaction
async function processTransaction(transaction) {
  // First, analyze sender
  const senderAnalysis = await analyzeEntity(
    transaction.senderId,
    'person'
  );

  // Then analyze receiver
  const receiverAnalysis = await analyzeEntity(
    transaction.receiverId,
    'person'
  );

  // Calculate combined risk
  const combinedRisk = Math.max(
    senderAnalysis.data.overallRiskScore,
    receiverAnalysis.data.overallRiskScore
  );

  if (combinedRisk >= 80) {
    return { approved: false, reason: 'High risk participants' };
  }

  return { approved: true };
}

Next Steps

Create Risk Matrix - Configure your risk assessment rules
Create Rule - Add individual rules to your matrix
Execute Enrichment - Enrich data before analysis
List Alerts - View alerts generated by rules
Provider Codes Reference - Available enrichment providers

⌘I

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Examples

​Basic Risk Matrix Execution

​Execute with Auto-Enrichment

​Execute with Specific Enrichments

​Response Example

​Successful Analysis

​No Active Rules Warning

​Incomplete Data Coverage

​Risk Levels

​Rule Actions

​Error Responses

​404 Not Found - Entity Not Found

​401 Unauthorized

​422 Unprocessable Entity - Incomplete Data

​Real-Time Notifications

​Best Practices

​Use Cases

​Onboarding Risk Assessment

​Periodic Re-assessment

​Transaction Risk Scoring

​Next Steps

Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Examples

Basic Risk Matrix Execution

Execute with Auto-Enrichment

Execute with Specific Enrichments

Response Example

Successful Analysis

No Active Rules Warning

Incomplete Data Coverage

Risk Levels

Rule Actions

Error Responses

404 Not Found - Entity Not Found

401 Unauthorized

422 Unprocessable Entity - Incomplete Data

Real-Time Notifications

Best Practices

Use Cases

Onboarding Risk Assessment

Periodic Re-assessment

Transaction Risk Scoring

Next Steps