1. Overview

The Diliguard Developer API (v2) gives engineering teams programmatic access to our intelligence engine. It features:

• API key authentication: Every request requires a valid X-API-Key header.
• Credit-based accounting: Each scan or workflow consumes fixed credits from your subscription.
• Per-organization rate limits: Requests-per-minute caps enforced automatically on a 60-second rolling window.
• Audit trail logging: Every transaction is logged with unique request IDs for compliance records.

API Categories Summary

Category	Endpoints	Credits per Request
Account Management	3	0 (Free)
Single Intelligence Scans	18	1 Credit
Composite Workflows	7	5 to 15 Credits

Public Health Check (No Auth Required)

GET https://api.diliguard.com/health

{
  "status": "ok"
}

2. Quickstart

Execute your first request in three steps:

Step 1: Create an API Key

Generate an API key from the Diliguard Portal or create a sub-token programmatically:

curl -X POST https://api.diliguard.com/api/v2/account/keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_INITIAL_API_KEY" \
  -d '{"name": "Production Integration"}'

Step 2: Make a Scan Request

curl -X POST https://api.diliguard.com/api/v2/scan-sanctions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{"target_name": "Volkswagen AG"}'

Step 3: Read the Response Envelope

{
  "success": true,
  "data": {
    "status": "clear",
    "risk_score": 0,
    "sanctions_matches": [],
    "lists_checked": ["OFAC_SDN", "UN_SANCTIONS", "EU_SANCTIONS", "HMT_SANCTIONS"]
  },
  "credits": {
    "used": 1,
    "limit": 500,
    "remaining": 499
  },
  "request_id": "req_a1b2c3d4e5f6"
}

3. Authentication

Every request to /api/v2/* must include the X-API-Key header. The API key connects your request to your organization, subscription tier, credit quota, and rate limits.

Authentication Error Dictionary

Stage	HTTP Status	Error Code	Description
Invalid Key	401	INVALID_API_KEY	API key is missing, inactive, or malformed.
Token Owner Missing	401	INVALID_API_KEY	Key owner account is inactive.
Organization Missing	403	INVALID_API_KEY	Organization record not found.
No Active Plan	403	NO_SUBSCRIPTION	No active subscription found for organization.
Credit Cap Hit	429	CREDIT_LIMIT_EXCEEDED	Monthly credit quota reached. Resets on period end.
Rate Limit Hit	429	RATE_LIMIT_EXCEEDED	Organization exceeded requests per minute limit.

4. Credit System & Cost Schedule

Credits are allocated monthly based on your subscription tier. Each scan deducts credits upon successful execution. Failed backend calls do not deduct credits.

Endpoint	Cost	Category	Description
POST /scan-sanctions	1 Credit	Corporate/AML	Match against OFAC, UN, EU, UK HMT watchlists.
POST /scan-pep	1 Credit	Corporate/AML	Politically Exposed Persons verification.
POST /scan-corporate-intel	1 Credit	Corporate/AML	GLEIF LEI, registration, and status lookup.
POST /scan-ubo	1 Credit	Corporate/AML	Beneficial ownership graph across 16 jurisdictions.
POST /scan-regulatory	1 Credit	Corporate/AML	Enforcement actions and regulatory penalties.
POST /scan-offshore	1 Credit	Corporate/AML	Screening across global offshore leak records.
POST /scan-crypto	1 Credit	Financial	Multi-chain wallet address balance and cluster analysis.
POST /scan-crypto-activity	1 Credit	Financial	Transaction history and interaction timing.
POST /scan-crypto-illicit	1 Credit	Financial	Direct exposure to mixers, hacks, and sanctioned pools.
POST /scan-iban	1 Credit	Financial	IBAN formatting, checksum, and routing bank verification.
POST /scan-vat	1 Credit	Financial	Live European VAT verification via VIES.
POST /scan-media	1 Credit	Digital OSINT	Adverse media and negative news indexing.
POST /scan-domain	1 Credit	Digital OSINT	WHOIS, DNS records, MX routing, and reputation.
POST /scan-phone	1 Credit	Digital OSINT	Carrier, line type, country code, and fraud score.
POST /scan-username	1 Credit	Digital OSINT	Cross-platform social media and account footprint.
POST /scan-ip	1 Credit	Digital OSINT	Geolocation, proxy, VPN, Tor, and datacenter check.
POST /scan-darkweb	1 Credit	Digital OSINT	Compromised credential and breach database check.
POST /workflow-corporate	5 Credits	Workflow	Combined KYB, UBO, sanctions, and media check.
POST /workflow-person	5 Credits	Workflow	Comprehensive individual background and PEP sweep.
POST /workflow-crypto	5 Credits	Workflow	End-to-end blockchain asset and counterparty trace.
POST /workflow-vendor-risk	10 Credits	Workflow	Multi-entity supply chain risk and regulatory sweep.
POST /workflow-ultimate-fraud	15 Credits	Workflow	Holistic corporate, executive, and digital forensics.
POST /registry-entity-research	5 Credits	Workflow	Deep multi-registry corroboration and document audit.
GET /account/*	0 Credits	Account	Usage, history, and key management endpoints.

5. Rate Limits & Response Format

Rate limits are enforced on a rolling 60-second window. Every response includes real-time quota status in the HTTP headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57

Standard Response Envelope

{
  "success": true,
  "data": {
    /* Endpoint specific data object */
  },
  "credits": {
    "used": 12,
    "limit": 500,
    "remaining": 488
  },
  "request_id": "req_8f1a2b3c4d5e"
}

Standard Error Envelope

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Requests per minute limit reached (60/60). Wait 12 seconds."
  }
}

6. Account Management Endpoints

Account endpoints are free (0 credits) and allow you to inspect usage, review scan logs, and manage tokens.

GET /api/v2/account/usage

Returns subscription plan limits and credits consumed in the current billing period.

curl -X GET https://api.diliguard.com/api/v2/account/usage \
  -H "X-API-Key: dg_live_abc123def456"

{
  "org_name": "Acme Holdings",
  "plan_name": "Professional",
  "credits_used": 47,
  "credits_limit": 500,
  "period_end": "2026-11-01T00:00:00.000Z"
}

GET /api/v2/account/history

Returns paginated history of past scans. Supports query filters: page, per_page, scan_type, status, source.

curl -X GET "https://api.diliguard.com/api/v2/account/history?page=1&per_page=10" \
  -H "X-API-Key: dg_live_abc123def456"

POST /api/v2/account/keys

Generates a new API key for your organization.

curl -X POST https://api.diliguard.com/api/v2/account/keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{"name": "CI/CD Deployment Key"}'

{
  "key_id": "key_9x8y7z",
  "name": "CI/CD Deployment Key",
  "token": "dg_live_newtoken123456789...",
  "created_at": "2026-10-05T12:00:00.000Z"
}

7. Corporate & AML Scans

Verify companies, screen beneficial owners, and inspect international sanctions registers.

POST /api/v2/scan-ubo

Unwrap ultimate beneficial ownership and shareholding structures across 16 global jurisdictions concurrently.

Parameter	Type	Required	Description
company_name	string	Yes	Official legal entity name to unwrap.
jurisdiction	string	No	Target country code (e.g. ‘GB’, ‘DE’, ‘FR’, ‘NL’) or ‘GLOBAL’.

curl -X POST https://api.diliguard.com/api/v2/scan-ubo \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{"company_name": "Deutsche Bank AG", "jurisdiction": "DE"}'

{
  "success": true,
  "data": {
    "status": "clear",
    "jurisdiction": "DE",
    "total_hits": 1,
    "companies": [
      {
        "company_name": "Deutsche Bank AG",
        "registration_number": "HRB 30000",
        "registered_address": "Taunusanlage 12, Frankfurt am Main",
        "status": "active",
        "beneficial_owners": [
          {
            "name": "Institutional Float",
            "ownership_percentage": 100.0,
            "nature_of_control": "publicly_traded"
          }
        ]
      }
    ]
  },
  "credits": { "used": 1, "limit": 500, "remaining": 499 },
  "request_id": "req_ubo_77123"
}

POST /api/v2/scan-sanctions

Check individual or entity names against OFAC SDN, UN Consolidated, EU Financial Sanctions, and UK HMT.

Parameter	Type	Required	Description
target_name	string	Yes	Full person or company name to screen.

curl -X POST https://api.diliguard.com/api/v2/scan-sanctions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{"target_name": "Siemens AG"}'

8. Financial & Crypto Forensics

Analyze blockchain transaction flows, identify illicit mixer exposure, and validate bank accounts.

POST /api/v2/scan-crypto-illicit

Screen cryptocurrency wallet addresses for direct exposure to sanctioned entities, darknet markets, or crypto mixers.

Parameter	Type	Required	Description
wallet_address	string	Yes	Cryptocurrency public address (BTC, ETH, SOL, etc.).
blockchain	string	No	Specific network code (default: auto-detected).

curl -X POST https://api.diliguard.com/api/v2/scan-crypto-illicit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{"wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'

POST /api/v2/scan-iban

Validate International Bank Account Numbers for structural validity, checksum integrity, and routing bank status.

curl -X POST https://api.diliguard.com/api/v2/scan-iban \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{"iban": "DE89370400440532013000"}'

9. Digital OSINT & Composite Workflows

Investigate domains, IPs, and phone numbers, or execute multi-stage due diligence workflows with one call.

POST /api/v2/workflow-corporate (5 Credits)

Executes full corporate due diligence: registry verification, LEI validation, sanctions screening, regulatory check, adverse media, and UBO unwrapping.

curl -X POST https://api.diliguard.com/api/v2/workflow-corporate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{"company_name": "Airbus SE", "country": "FR"}'

POST /api/v2/workflow-ultimate-fraud (15 Credits)

Holistic forensic investigation combining corporate registry checks, executive person trace, digital domain footprint, and transaction risk scoring.

curl -X POST https://api.diliguard.com/api/v2/workflow-ultimate-fraud \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_live_abc123def456" \
  -d '{
    "company_name": "Apex Global Logistics Ltd",
    "person_name": "Marcus Vance",
    "domain": "apex-global-logistics.com",
    "wallet_address": "0x71C...8976"
  }'

10. Error Reference & Client Libraries

The API returns standard HTTP status codes. Detailed error reasons are included in the JSON body:

HTTP Status	Error Code	Meaning
400 Bad Request	INVALID_PARAMS	Request body is malformed or missing required fields.
401 Unauthorized	INVALID_API_KEY	API key missing, inactive, or invalid.
403 Forbidden	NO_SUBSCRIPTION	Account does not have an active subscription.
422 Unprocessable	VALIDATION_FAILED	Input parameter failed format validation.
429 Too Many Requests	RATE_LIMIT_EXCEEDED	Request exceeded per-minute quota threshold.
429 Too Many Requests	CREDIT_LIMIT_EXCEEDED	Monthly credit balance exhausted.
502 Bad Gateway	BACKEND_ERROR	Underlying intelligence engine returned an error.
504 Gateway Timeout	TIMEOUT	Query exceeded maximum execution window (120 seconds).

Python SDK Snippet

import requests

class DiliguardClient:
    def __init__(self, api_key: str, base_url: str = "https://api.diliguard.com"):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "Content-Type": "application/json",
            "X-API-Key": self.api_key
        })

    def scan_sanctions(self, target_name: str) -> dict:
        url = f"{self.base_url}/api/v2/scan-sanctions"
        res = self.session.post(url, json={"target_name": target_name})
        res.raise_for_status()
        return res.json()

    def scan_ubo(self, company_name: str, jurisdiction: str = "GLOBAL") -> dict:
        url = f"{self.base_url}/api/v2/scan-ubo"
        res = self.session.post(url, json={"company_name": company_name, "jurisdiction": jurisdiction})
        res.raise_for_status()
        return res.json()

# Usage
client = DiliguardClient("dg_live_abc123def456")
result = client.scan_ubo("Siemens AG")
print(result)