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

import requests

url = "http://api.gu1.ai/entities/{entityId}/analyze"

payload = {
    "entityType": "<string>",
    "enrichIfNeeded": True,
    "providerCodes": [{}],
    "rulesEngineConfig": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityType: '<string>',
    enrichIfNeeded: true,
    providerCodes: [{}],
    rulesEngineConfig: {}
  })
};

fetch('http://api.gu1.ai/entities/{entityId}/analyze', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{entityId}/analyze",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityType' => '<string>',
    'enrichIfNeeded' => true,
    'providerCodes' => [
        [
                
        ]
    ],
    'rulesEngineConfig' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{entityId}/analyze"

	payload := strings.NewReader("{\n  \"entityType\": \"<string>\",\n  \"enrichIfNeeded\": true,\n  \"providerCodes\": [\n    {}\n  ],\n  \"rulesEngineConfig\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/{entityId}/analyze")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityType\": \"<string>\",\n  \"enrichIfNeeded\": true,\n  \"providerCodes\": [\n    {}\n  ],\n  \"rulesEngineConfig\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{entityId}/analyze")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityType\": \"<string>\",\n  \"enrichIfNeeded\": true,\n  \"providerCodes\": [\n    {}\n  ],\n  \"rulesEngineConfig\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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

import requests

url = "http://api.gu1.ai/entities/{entityId}/analyze"

payload = {
    "entityType": "<string>",
    "enrichIfNeeded": True,
    "providerCodes": [{}],
    "rulesEngineConfig": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityType: '<string>',
    enrichIfNeeded: true,
    providerCodes: [{}],
    rulesEngineConfig: {}
  })
};

fetch('http://api.gu1.ai/entities/{entityId}/analyze', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{entityId}/analyze",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityType' => '<string>',
    'enrichIfNeeded' => true,
    'providerCodes' => [
        [
                
        ]
    ],
    'rulesEngineConfig' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{entityId}/analyze"

	payload := strings.NewReader("{\n  \"entityType\": \"<string>\",\n  \"enrichIfNeeded\": true,\n  \"providerCodes\": [\n    {}\n  ],\n  \"rulesEngineConfig\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/{entityId}/analyze")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityType\": \"<string>\",\n  \"enrichIfNeeded\": true,\n  \"providerCodes\": [\n    {}\n  ],\n  \"rulesEngineConfig\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{entityId}/analyze")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityType\": \"<string>\",\n  \"enrichIfNeeded\": true,\n  \"providerCodes\": [\n    {}\n  ],\n  \"rulesEngineConfig\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

UUID of the entity to analyze

Request Body

string

required

Entity type: person, company, or transaction

boolean

default:"false"

Whether to run enrichment before analysis

array

Specific provider codes to execute for enrichment

object

Per-run rules engine behavior. All fields optional; omitted fields default to false.

partialCoverage (boolean, default false): With multiple assigned risk matrices, validate data coverage per matrix. Matrices without coverage are skipped; others still run. If none have coverage, returns 422.
omitCoverage (boolean, default false): Skip data coverage gates entirely (main entity pre-check and shareholder coverage). Takes precedence over partialCoverage when both are true.

Does not change org-level shareholderCoverageMode.

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"
    ]
  }'

Multi-Matrix Analysis with Per-Matrix Coverage

Use when an entity has several risk matrices but you want matrices with sufficient data to run even if others are missing enrichments:

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",
    "rulesEngineConfig": {
      "partialCoverage": true
    }
  }'

Response - Success

The response includes data (analysis details), and when rules ran also rulesResult and rulesExecutionSummary at the root (same as create, enrich, refresh).

object

Full rules execution result when analysis ran: success, executed, result, rulesTriggered, executionTimeMs, auditId, isNewAudit, rulesExecutionSummary (same object as root field below).

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 - Partial matrix execution (`rulesEngineConfig.partialCoverage: true`)

When some assigned matrices lack data coverage but at least one matrix can run, the request succeeds (200). Skipped matrices are listed at the root:

{
  "success": true,
  "data": { "entityId": "entity-123", "overallRiskScore": 42 },
  "rulesExecutionSummary": { "totalScore": 42 },
  "warnings": [
    "Risk matrix Onboarding missing enrichment for field sanctioned"
  ],
  "matricesSkippedForCoverage": [
    {
      "riskMatrixId": "rm-onboarding",
      "riskMatrixName": "Onboarding",
      "errorCode": "INCOMPLETE_DATA_COVERAGE",
      "coverageSummary": "Risk matrix Onboarding missing enrichment for field sanctioned"
    }
  ]
}

The audit row stores executed matrix IDs in risk_matrix_ids; skipped matrices appear in analysisResult.matricesSkippedForCoverage.

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']}")

​Overview

​Endpoint

​Path Parameters

​Request Body

​Example Requests

​Basic Analysis

​Analysis with Enrichment

​Analysis with Specific Providers

​Multi-Matrix Analysis with Per-Matrix Coverage

​Response - Success

​Response - Partial matrix execution (rulesEngineConfig.partialCoverage: true)

​Response - No Rules Configured

​Response - Incomplete Data

​Risk Levels

​Use Cases

​Analyze After Data Update

​Batch Analysis

​See Also

Overview

Endpoint

Path Parameters

Request Body

Example Requests

Basic Analysis

Analysis with Enrichment

Analysis with Specific Providers

Multi-Matrix Analysis with Per-Matrix Coverage

Response - Success

Response - Partial matrix execution (`rulesEngineConfig.partialCoverage: true`)

Response - No Rules Configured

Response - Incomplete Data

Risk Levels

Use Cases

Analyze After Data Update

Batch Analysis

See Also