# UtilityPro API — Full Reference

Base URL: `https://secure.utilitypro.eu/api/v1`

Authentication: send your API key in the `x-api-key` header (or `Authorization: Bearer <jwt>` for endpoints marked JWT). Every request is served over HTTPS.

Machine-readable spec: [openapi.json](https://www.utilitypro.eu/openapi.json)

## Categories
- **Payment Validation** — Validate international payment requirements for 147+ countries and currencies (base: `/v1/payment-validation`, auth: api-key)
- **Data Tools** — Email/phone validation, data cleansing, and fuzzy name matching (base: `/v1/data-tools`, auth: api-key)
- **Banking Tools** — IBAN, BIC/SWIFT, IFSC, and BIN/IIN validation and lookup (base: `/v1/banking-tools`, auth: api-key)
- **Security Tools** — Domain lookup, IP intelligence, blocklist checks, and threat detection (base: `/v1/security-tools`, auth: api-key)
- **Device Intelligence** — White-label device fingerprinting, bot detection, VPN/proxy/incognito/tampering signals and visitor history (base: `/v1/device-intel-tools`, auth: api-key)
- **Geolocation** — IP geolocation, reverse geocoding, and address validation (base: `/v1/geolocation-tools`, auth: api-key)
- **Imaging Tools** — QR code generation and image processing (base: `/v1/imaging-tools`, auth: api-key)
- **Telephony & SMS** — Phone verification, SMS sending, and HLR lookups (base: `/v1/telephony-tools`, auth: api-key)
- **Blockchain Tools** — Multi-chain wallet validation, transaction lookup, and balance queries (base: `/v1/blockchain-tools`, auth: api-key)
- **Blockchain Compliance** — AML/CFT risk scoring for blockchain transactions, addresses, and wallets (base: `/v1/compliance-tools`, auth: api-key)
- **Email API** — Transactional email sending with custom domain support (base: `/v1/email`, auth: api-key)
- **SwiftHub** — SWIFT payment processing, validation, and message handling (base: `/v1/swifthub`, auth: jwt)
- **VAT Validation** — EU VAT number validation and company lookup (base: `/v1/vat-validation`, auth: api-key)
- **KYB / Business Registry** — Global Legal Entity Identifier (LEI) lookup and company registry search via GLEIF (base: `/v1/kyb-tools`, auth: api-key)
- **Sanctions & PEP Screening** — Screen names against OFAC SDN, EU, UN, UK and global PEP lists (base: `/v1/sanctions-tools`, auth: api-key)
- **Banking Calendar** — Public holidays and business-day arithmetic for settlement and SLA calculations (base: `/v1/calendar-tools`, auth: api-key)
- **Reference Data** — Country reference data, FX rates, and global VAT rate lookup (base: `/v1/reference-tools`, auth: api-key)


---

## Payment Validation

Validate international payment requirements for 147+ countries and currencies

- Base URL: `https://secure.utilitypro.eu/api/v1/payment-validation`
- Auth: `x-api-key` (api-key)

Notes:
- Supports SEPA, SWIFT, and local payment schemes
- Returns IBAN formats, routing codes, and purpose codes

### GET /requirements — Get Payment Requirements

Retrieve payment field requirements for a country and/or currency, optionally filtered by transfer type

Returns comprehensive payment validation rules including required fields, IBAN formats, routing codes, and purpose of payment codes for international wire transfers. Supports a discovery flow: query with only country_code to see available currencies and their valid transfer types, then refine with currency_code and transfer_type for filtered requirements.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `country_code` | string | no | ISO 2-letter country code | `DE` |
| `currency_code` | string | no | ISO 3-letter currency code | `EUR` |
| `transfer_type` | string | no | Transfer type to filter requirements: domestic, sepa, or international. Omit to get all requirements. | `sepa` |

**Example request body:**
```json
{
  "country_code": "DE",
  "currency_code": "EUR",
  "transfer_type": "sepa"
}
```

**Example response:**
```json
{
  "success": true,
  "country": {
    "code": "DE",
    "name": "Germany"
  },
  "currency": {
    "code": "EUR",
    "name": "Euro"
  },
  "available_transfer_types": [
    "domestic",
    "sepa",
    "international"
  ],
  "transfer_type": "sepa",
  "clearing_hint": "SEPA SCT",
  "is_domestic": false,
  "is_sepa": true,
  "requirements": {
    "bank_details": {
      "iban": {
        "required": true,
        "format": "DE[0-9]{2}[0-9]{18}",
        "length": 22
      },
      "bic": {
        "required": false,
        "format": "[A-Z]{4}DE[A-Z0-9]{2}([A-Z0-9]{3})?"
      }
    },
    "beneficiary_info": {
      "beneficiary_name": {
        "required": true,
        "max_length": 70
      },
      "beneficiary_address": {
        "required": true
      }
    },
    "regulatory": {
      "purpose_code": {
        "required": false,
        "codes": [
          "SALA",
          "PENS",
          "TRAD"
        ]
      }
    }
  },
  "routing_codes": [],
  "purpose_of_payment_codes": []
}
```

Notes:
- At least one of country_code or currency_code is required
- Combine both for most accurate requirements
- Use transfer_type to filter requirements for a specific clearing network (domestic, sepa, international)
- Omitting transfer_type returns all requirements unfiltered (backward compatible)
- The response includes available_transfer_types so clients can discover valid options
- SEPA is only available for SEPA-zone countries with eligible currencies (EUR, SEK, DKK, CHF, etc.)

### GET /countries — List Countries

Get all supported countries with their ISO codes

**Example response:**
```json
{
  "success": true,
  "countries": [
    {
      "code": "DE",
      "name": "Germany",
      "currency": "EUR"
    },
    {
      "code": "US",
      "name": "United States",
      "currency": "USD"
    },
    {
      "code": "GB",
      "name": "United Kingdom",
      "currency": "GBP"
    }
  ],
  "total": 147
}
```

### GET /currencies — List Currencies

Get all supported currencies with their ISO codes

**Example response:**
```json
{
  "success": true,
  "currencies": [
    {
      "code": "EUR",
      "name": "Euro",
      "countries": [
        "DE",
        "FR",
        "ES",
        "IT"
      ]
    },
    {
      "code": "USD",
      "name": "US Dollar",
      "countries": [
        "US"
      ]
    },
    {
      "code": "GBP",
      "name": "British Pound",
      "countries": [
        "GB"
      ]
    }
  ],
  "total": 180
}
```

---

## Data Tools

Email/phone validation, data cleansing, and fuzzy name matching

- Base URL: `https://secure.utilitypro.eu/api/v1/data-tools`
- Auth: `x-api-key` (api-key)

### POST /email-validate — Email Validate

Parse, validate and clean email addresses

Validates email syntax, checks DNS/MX records, detects freemails and disposable emails, and can auto-fix common domain typos.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `email` | string | yes | Email address to validate | `test@example.com` |
| `fix_typos` | boolean | no | Auto-fix common domain typos | `true` |

**Example request body:**
```json
{
  "email": "test@example.com",
  "fix_typos": true
}
```

**Example response:**
```json
{
  "valid": true,
  "syntax-error": false,
  "domain": "example.com",
  "domain-error": false,
  "is-freemail": false,
  "is-disposable": false,
  "is-personal": true,
  "provider": "Example Inc",
  "email": "test@example.com"
}
```

### POST /email-verify — Email Verify (SMTP)

Real-time SMTP verification to check email deliverability

Performs actual SMTP handshake to verify if an email address can receive mail. More thorough than basic validation.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `email` | string | yes | Email address to verify | `test@example.com` |
| `fix_typos` | boolean | no | Auto-fix common domain typos | `false` |

**Example request body:**
```json
{
  "email": "test@example.com"
}
```

**Example response:**
```json
{
  "valid": true,
  "verified": true,
  "email": "test@example.com",
  "domain": "example.com",
  "is-freemail": false,
  "is-disposable": false,
  "is-catch-all": false,
  "smtp-status": "ok",
  "smtp-response": "250 2.1.5 OK"
}
```

Notes:
- SMTP verification may take 2-5 seconds
- Some servers block verification attempts

### POST /phone-validate — Phone Validate

Parse, validate and get carrier information for phone numbers

Validates phone number format, determines carrier/network, location, and formats to international/local standards.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `number` | string | yes | Phone number (local or international) | `+14158586273` |
| `country_code` | string | no | ISO 2-letter country code for local numbers | `US` |
| `ip` | string | no | User IP to determine country | `8.8.8.8` |

**Example request body:**
```json
{
  "number": "+14158586273",
  "country_code": "US"
}
```

**Example response:**
```json
{
  "valid": true,
  "international-number": "+1 415-858-6273",
  "local-number": "(415) 858-6273",
  "country": "United States",
  "country-code": "US",
  "country-code3": "USA",
  "currency-code": "USD",
  "location": "California",
  "is-mobile": true,
  "type": "mobile",
  "international-calling-code": "1",
  "prefix-network": "T-Mobile"
}
```

### POST /bad-word-filter — Bad Word Filter

Detect and censor profanity in text content

Scans text for profanity, slurs, and inappropriate content. Can censor or flag offensive words.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `content` | string | yes | Text content to filter | `This is some text` |
| `censor_character` | string | no | Character to replace bad words | `*` |

**Example request body:**
```json
{
  "content": "This is some clean text",
  "censor_character": "*"
}
```

**Example response:**
```json
{
  "is-bad": false,
  "bad-words-list": [],
  "bad-words-total": 0,
  "censored-content": "This is some clean text"
}
```

### POST /convert — Unit Convert

Convert between units and currencies

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `from_value` | number | yes | Value to convert | `100` |
| `from_type` | string | yes | Source unit/currency | `USD` |
| `to_type` | string | yes | Target unit/currency | `EUR` |

**Example request body:**
```json
{
  "from_value": 100,
  "from_type": "USD",
  "to_type": "EUR"
}
```

**Example response:**
```json
{
  "valid": true,
  "result": 91.25,
  "from-value": 100,
  "from-type": "USD",
  "to-type": "EUR",
  "result-float": 91.25
}
```

### POST /name-match — Name Match

Fuzzy name matching for individuals and corporate entities

Advanced name matching supporting two modes: individual (person) and corporate (entity/company). Includes Arabic→Latin and Cyrillic→Latin transliteration, batch matching (up to 100 pairs per call), and confidence metadata (processing_time_ms, match_quality). Individual mode uses Jaro-Winkler and Levenshtein similarity with weighted first/middle/last name buckets. Corporate mode uses legal suffix normalisation and flat token-set scoring.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `left_name` | string | yes | First name to compare (single mode) | `Dr. John Robert Smith` |
| `right_name` | string | yes | Second name to compare (single mode) | `Smith John R` |
| `type` | string | no | Match mode: 'individual' (default) or 'corporate' | `individual` |
| `pairs` | array | no | Array of {left_name, right_name, type?} for batch mode (max 100 pairs). Omit left_name/right_name when using pairs. | `[{"left_name":"John Smith","right_name":"Jon Smyth"}]` |

**Example request body:**
```json
{
  "left_name": "Dr. John Robert Smith",
  "right_name": "Smith John R",
  "type": "individual"
}
```

**Example response:**
```json
{
  "decision": "strong_match",
  "score": 0.965,
  "first_score": 1,
  "middle_score": 0.96,
  "last_score": 1,
  "token_set_score": 0.98,
  "considered_swap": true,
  "notes": "Used swapped First/Last. Missing middle(s) tolerated.",
  "reason_codes": [
    "swapped_first_last_used",
    "strong_core_match"
  ],
  "normalized_left_tokens": [
    "JOHN",
    "ROBERT",
    "SMITH"
  ],
  "normalized_right_tokens": [
    "SMITH",
    "JOHN",
    "R"
  ],
  "processing_time_ms": 1.24,
  "match_quality": "high"
}
```

Notes:
- Individual mode: decisions at strong_match (≥0.92), match (≥0.88), review (≥0.80), no_match (<0.80)
- Corporate mode: legal suffix normalisation (Ltd/LLC/GmbH/SA/BV/KK etc.), noise word filtering, flat token-set scoring
- Corporate mode: decisions at strong_match (≥0.92), match (≥0.85), review (≥0.78), no_match (<0.78)
- Batch mode: send 'pairs' array with up to 100 {left_name, right_name} objects; returns results[] with index
- Transliteration: Arabic and Cyrillic scripts auto-converted to Latin before matching
- Confidence metadata: processing_time_ms and match_quality (high/medium/low) included in every response
- Handles honorifics (Mr, Mrs, Dr, Prof, Shri, etc.) in individual mode
- Filters low-signal tokens (BIN, BINTI, VON, S/O, D/O, etc.) in individual mode
- Expands combined initials (RK → R, K) in individual mode
- Automatically tests first/last name swap in individual mode

### POST /disposable-email-check — Disposable Email Check

Detect throwaway / temporary email providers

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `email` | string | yes | Email to check | `foo@mailinator.com` |

**Example request body:**
```json
{
  "email": "foo@mailinator.com"
}
```

**Example response:**
```json
{
  "email": "foo@mailinator.com",
  "domain": "mailinator.com",
  "is_disposable": true,
  "provider": "disposable-email-domains"
}
```

### POST /mx-validate — MX Record Validation

Verify a domain (or email domain) has valid MX records

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `domain` | string | no | Domain to check |  |
| `email` | string | no | Or pass an email to extract its domain |  |

**Example request body:**
```json
{
  "domain": "gmail.com"
}
```

**Example response:**
```json
{
  "domain": "gmail.com",
  "has_mx": true,
  "mx_records": [
    {
      "priority": 5,
      "exchange": "gmail-smtp-in.l.google.com"
    }
  ],
  "primary": "gmail-smtp-in.l.google.com",
  "provider": "google-dns"
}
```

---

## Banking Tools

IBAN, BIC/SWIFT, IFSC, and BIN/IIN validation and lookup

- Base URL: `https://secure.utilitypro.eu/api/v1/banking-tools`
- Auth: `x-api-key` (api-key)

### POST /iban-lookup — IBAN Lookup

Validate IBAN and retrieve bank details

Validates IBAN structure and checksum, extracts bank and account details, identifies SEPA support.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `iban` | string | yes | Full IBAN number | `DE89370400440532013000` |

**Example request body:**
```json
{
  "iban": "DE89370400440532013000"
}
```

**Example response:**
```json
{
  "result": 200,
  "message": "Valid IBAN Number",
  "data": {
    "country_code": "DE",
    "iban": "DE89370400440532013000",
    "bban": "370400440532013000",
    "bank": {
      "bank_name": "Commerzbank",
      "bank_code": "37040044",
      "branch": "Frankfurt",
      "address": "Kaiserplatz, Frankfurt am Main",
      "bic": "COBADEFFXXX",
      "country": "Germany"
    },
    "sepa": {
      "sepa_credit_transfer": true,
      "sepa_direct_debit": true,
      "sepa_instant_credit_transfer": true
    }
  },
  "validations": [
    {
      "code": "001",
      "message": "IBAN structure is correct"
    }
  ]
}
```

### POST /bic-lookup — BIC/SWIFT Lookup

Get bank details from BIC/SWIFT code

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `bic` | string | yes | BIC/SWIFT code (8 or 11 characters) | `COBADEFFXXX` |

**Example request body:**
```json
{
  "bic": "COBADEFFXXX"
}
```

**Example response:**
```json
{
  "valid": true,
  "bic": "COBADEFFXXX",
  "bank-name": "Commerzbank AG",
  "bank-code": "37040044",
  "branch": "Head Office",
  "address": "Kaiserplatz, Frankfurt am Main",
  "city": "Frankfurt am Main",
  "country": "Germany",
  "country-code": "DE",
  "is-primary": true
}
```

### POST /ifsc-lookup — IFSC Lookup

Validate Indian Financial System Code (IFSC)

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `ifsc` | string | yes | IFSC code (11 characters) | `SBIN0001234` |

**Example request body:**
```json
{
  "ifsc": "SBIN0001234"
}
```

**Example response:**
```json
{
  "valid": true,
  "ifsc": "SBIN0001234",
  "bank": "State Bank of India",
  "branch": "New Delhi Main Branch",
  "address": "11, Parliament Street, New Delhi",
  "city": "New Delhi",
  "district": "Central Delhi",
  "state": "Delhi",
  "contact": "011-23374131",
  "micr": "110002001",
  "upi": true,
  "neft": true,
  "rtgs": true,
  "imps": true
}
```

### POST /bin-lookup — BIN Lookup

Get card issuer information from BIN/IIN number

Looks up card issuer details including bank name, card type (credit/debit), brand (Visa/Mastercard), and country of issue.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `bin_number` | string | yes | First 6-8 digits of card number (legacy alias: binNumber) | `45717360` |

**Example request body:**
```json
{
  "bin_number": "45717360"
}
```

**Example response:**
```json
{
  "valid": true,
  "bin-number": "45717360",
  "card-brand": "Visa",
  "card-type": "Credit",
  "card-category": "Classic",
  "issuer": "Bank of America",
  "issuer-website": "https://www.bankofamerica.com",
  "issuer-phone": "+1-800-732-9194",
  "country": "United States",
  "country-code": "US",
  "is-commercial": false,
  "is-prepaid": false
}
```

---

## Security Tools

Domain lookup, IP intelligence, blocklist checks, and threat detection

- Base URL: `https://secure.utilitypro.eu/api/v1/security-tools`
- Auth: `x-api-key` (api-key)

### POST /domain-lookup — Domain Lookup

Get DNS and WHOIS information for a domain

Retrieves comprehensive domain information including DNS records, WHOIS data, registrar details, and domain age.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `host` | string | yes | Domain name to lookup | `example.com` |
| `live` | boolean | no | Force live DNS lookup | `true` |

**Example request body:**
```json
{
  "host": "example.com",
  "live": true
}
```

**Example response:**
```json
{
  "valid": true,
  "host": "example.com",
  "registrar": "ICANN",
  "registered-date": "1995-08-14T04:00:00Z",
  "age-years": 29,
  "dns-records": {
    "a": [
      "93.184.216.34"
    ],
    "aaaa": [
      "2606:2800:220:1:248:1893:25c8:1946"
    ],
    "mx": [
      "mail.example.com"
    ],
    "ns": [
      "ns1.example.com",
      "ns2.example.com"
    ],
    "txt": [
      "v=spf1 include:_spf.example.com ~all"
    ]
  },
  "is-adult": false,
  "is-malware": false,
  "is-phishing": false
}
```

### POST /ip-probe — IP Probe

Get detailed IP intelligence and risk scoring

Comprehensive IP analysis including geolocation, ISP details, proxy/VPN detection, and threat intelligence.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `ip` | string | yes | IPv4 or IPv6 address | `8.8.8.8` |

**Example request body:**
```json
{
  "ip": "8.8.8.8"
}
```

**Example response:**
```json
{
  "valid": true,
  "ip": "8.8.8.8",
  "hostname": "dns.google",
  "provider-type": "hosting",
  "provider-description": "Google LLC",
  "provider-domain": "google.com",
  "provider-website": "https://google.com",
  "asn": "AS15169",
  "as-cidr": "8.8.8.0/24",
  "as-country-code": "US",
  "as-description": "GOOGLE",
  "city": "Mountain View",
  "region": "California",
  "region-code": "CA",
  "country": "United States",
  "country-code": "US",
  "is-isp": false,
  "is-hosting": true,
  "is-proxy": false,
  "is-vpn": false,
  "is-bogon": false,
  "vpn-domain": ""
}
```

Notes:
- Fraud signals available: is-vpn, is-proxy, is-hosting, is-bogon. Use /ip-blocklist for Tor/malware/spam list checks (returns is-tor, is-malware, is-spyware, sensors and lists[]).

### POST /ip-blocklist — IP Blocklist Check

Check IP against known blocklists and threat databases

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `ip` | string | yes | IPv4 or IPv6 address | `192.168.1.1` |
| `vpn_lookup` | boolean | no | Include VPN detection | `true` |

**Example request body:**
```json
{
  "ip": "8.8.8.8",
  "vpn_lookup": true
}
```

**Example response:**
```json
{
  "ip": "8.8.8.8",
  "is-listed": false,
  "is-hijacked": false,
  "is-spider": false,
  "is-tor": false,
  "is-dshield": false,
  "is-vpn": false,
  "is-proxy": false,
  "is-spyware": false,
  "blocklists": [],
  "sensors-triggered": 0,
  "list-count": 0
}
```

### POST /host-reputation — Host Reputation

Check host safety score and malware/phishing detection

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `host` | string | yes | Domain or URL to check | `example.com` |
| `list_rating` | number | no | Minimum blocklist rating threshold (1-3) | `1` |

**Example request body:**
```json
{
  "host": "example.com",
  "list_rating": 1
}
```

**Example response:**
```json
{
  "host": "example.com",
  "is-listed": false,
  "is-malware": false,
  "is-phishing": false,
  "is-hijacked": false,
  "lists": [],
  "list-count": 0,
  "last-scanned": "2024-01-15T12:00:00Z"
}
```

### POST /urlhaus-lookup — URLhaus Malware Lookup

Check a URL or host against the abuse.ch URLhaus malware feed

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `url` | string | no | Full URL to check |  |
| `host` | string | no | Hostname to check (use either url or host) |  |

**Example request body:**
```json
{
  "url": "http://example.com/malware.exe"
}
```

**Example response:**
```json
{
  "query": "http://example.com/malware.exe",
  "listed": false,
  "threat": null,
  "tags": [],
  "provider": "abuse.ch/urlhaus"
}
```

Notes:
- Free service. Optional URLHAUS_AUTH_KEY enables higher quotas.

---

## Device Intelligence

White-label device fingerprinting, bot detection, VPN/proxy/incognito/tampering signals and visitor history

- Base URL: `https://secure.utilitypro.eu/api/v1/device-intel-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Three-step integration: (1) POST /script from your backend to fetch the embed snippet, (2) paste the returned <script> on your site, (3) read fraud signals server-side via /get-info-byrequestid, /get-visitor-info, or /get-all-device-info-byrange using the same API key.
- Fully white-label — the snippet is served from secure.utilitypro.eu, so visitors never see a third-party fingerprinting domain.
- No FingerprintJS Pro account needed. UtilityPro proxies the underlying provider on your behalf.
- /generatepath and /collect are invoked automatically by the embedded snippet — you never call them yourself.
- Always call the data-retrieval endpoints from your backend so your API key is never exposed in the browser.

### POST /script — Generate Embed Script

Generate the white-label JavaScript snippet to embed on your website

Step 1 of the integration. Returns a ready-to-paste <script type="module"> block tied to your API key. Drop the snippet into your site (ideally just before </body> on pages you want to fingerprint — checkout, signup, login). On every page load it:
1. Loads the white-label fingerprinting module via /generatepath (proxied through UtilityPro — your visitors never see a third-party domain).
2. Collects a persistent visitorId + a per-page-view requestId.
3. POSTs those IDs to /collect along with an encrypted client token so we can attribute the data to your account.

After collection, use /get-info-byrequestid, /get-visitor-info, or /get-all-device-info-byrange (from your backend) to retrieve fraud signals, IP, geolocation, browser, bot/VPN/proxy/incognito/tampering detection and visitor history.

**Example request body:**
```json
{}
```

**Example response:**
```json
{
  "script": "<script type=\"module\">\nasync function loadDeviceIntel() {\n  /* fetches /generatepath, runs fingerprinting, POSTs result to /collect */\n}\nloadDeviceIntel();\n</script>"
}
```

Notes:
- Call this once from your backend, cache the returned snippet, then embed it in your HTML.
- The snippet is bound to the API key used to generate it — rotate your key and you must regenerate the snippet.
- No FingerprintJS Pro account required — UtilityPro proxies everything under your own domain.
- Place the snippet on pages where you want device intelligence (checkout, signup, login).

### GET /generatepath — Module Proxy (internal)

White-label proxy that serves the fingerprinting module to the embedded snippet

Called automatically by the embedded snippet — merchants should not call this directly. Exists so the fingerprinting module is served from secure.utilitypro.eu instead of a third-party domain, preserving your white-label experience and bypassing ad/tracker blockers that target known fingerprinting hosts.

**Example response:**
```json
{
  "_comment": "Returns JavaScript (application/javascript) — not JSON."
}
```

Notes:
- Internal — invoked by the snippet returned from /script.
- No authentication required (public proxy).

### POST /collect — Collect Visitor Data (internal)

Receives requestId + visitorId from the embedded snippet

Called automatically by the embedded snippet after fingerprinting completes — merchants should not call this directly. The snippet sends an encrypted clientToken that we decrypt to attribute the requestId/visitorId pair to your account. Once stored, the requestId can be looked up via /get-info-byrequestid.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `requestId` | string | yes | Per-page-view request ID produced by the fingerprinting module | `req_abc123` |
| `visitorId` | string | yes | Persistent visitor ID produced by the fingerprinting module | `vst_xyz789` |
| `clientToken` | string | yes | Encrypted token embedded in the generated snippet — identifies the merchant | `enc_...` |

**Example request body:**
```json
{
  "requestId": "req_abc123",
  "visitorId": "vst_xyz789",
  "clientToken": "enc_..."
}
```

**Example response:**
```json
{
  "success": true
}
```

Notes:
- Internal — invoked by the snippet returned from /script.
- Authenticated via the encrypted clientToken, not the x-api-key header.

### POST /get-info-byrequestid — Get Event by Request ID

Fetch full fraud intelligence for a single page view

Step 3 of the integration. Once your front-end has captured a requestId (typically you persist it in a hidden form field or session and POST it to your backend on submit), call this endpoint server-side to retrieve the full event — IP, geolocation, browser/OS/device, confidence score, bot/VPN/proxy/incognito/tampering signals, and first-seen/last-seen timestamps.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `requestId` | string | yes | Request ID captured by the embedded snippet for the page view you want to inspect | `req_abc123` |

**Example request body:**
```json
{
  "requestId": "req_abc123"
}
```

**Example response:**
```json
{
  "products": {
    "identification": {
      "data": {
        "visitorId": "vst_xyz789",
        "requestId": "req_abc123",
        "confidence": {
          "score": 0.99
        },
        "ip": "203.0.113.45",
        "ipLocation": {
          "city": "Dubai",
          "country": {
            "name": "United Arab Emirates",
            "code": "AE"
          }
        },
        "browserDetails": {
          "browserName": "Chrome",
          "browserVersion": "120.0.0",
          "os": "Windows",
          "osVersion": "10",
          "device": "Desktop"
        },
        "firstSeenAt": {
          "global": "2024-01-01T00:00:00Z",
          "subscription": "2024-06-01T00:00:00Z"
        }
      }
    },
    "botd": {
      "data": {
        "bot": {
          "result": "notDetected"
        }
      }
    },
    "vpn": {
      "data": {
        "result": false,
        "methods": []
      }
    },
    "proxy": {
      "data": {
        "result": false
      }
    },
    "incognito": {
      "data": {
        "result": false
      }
    },
    "tampering": {
      "data": {
        "result": false
      }
    }
  }
}
```

Notes:
- Only returns data for requestIds that belong to your account — cross-merchant lookups return 404.
- Call from your backend so the API key is never exposed to the browser.

### POST /get-visitor-info — Get Visitor History

Fetch the full history of page views for a single visitor

Use the persistent visitorId to retrieve every recorded event for that visitor across your site. Useful for risk-scoring repeat visitors, identifying account takeovers (same visitorId, different account), and detecting multi-accounting (same visitorId signing up many times).

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `visitorId` | string | yes | Persistent visitor ID | `vst_xyz789` |

**Example request body:**
```json
{
  "visitorId": "vst_xyz789"
}
```

**Example response:**
```json
{
  "visitorId": "vst_xyz789",
  "visits": [
    {
      "requestId": "req_abc123",
      "timestamp": 1736942400000,
      "ip": "203.0.113.45",
      "url": "https://yoursite.com/checkout",
      "confidence": {
        "score": 0.99
      }
    }
  ]
}
```

Notes:
- Only returns data for visitorIds that have at least one event on your account.

### POST /get-all-device-info-byrange — Get Events by Date Range

Bulk-export all device events captured within a date range

Returns the full event payload for every page view your snippet recorded between startDate and endDate. Use this for fraud reporting, batch risk-scoring, or feeding your data warehouse.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `startDate` | string | yes | ISO-8601 start timestamp (inclusive) | `2025-06-01T00:00:00Z` |
| `endDate` | string | yes | ISO-8601 end timestamp (inclusive) | `2025-06-10T23:59:59Z` |

**Example request body:**
```json
{
  "startDate": "2025-06-01T00:00:00Z",
  "endDate": "2025-06-10T23:59:59Z"
}
```

**Example response:**
```json
{
  "events": [
    {
      "products": {
        "identification": {
          "data": {
            "visitorId": "vst_xyz789",
            "requestId": "req_abc123",
            "ip": "203.0.113.45"
          }
        },
        "botd": {
          "data": {
            "bot": {
              "result": "notDetected"
            }
          }
        }
      }
    }
  ]
}
```

Notes:
- Each event in the array counts as one API call against your plan.
- Keep ranges narrow (a day or two at a time) for large traffic volumes.

---

## Geolocation

IP geolocation, reverse geocoding, and address validation

- Base URL: `https://secure.utilitypro.eu/api/v1/geolocation-tools`
- Auth: `x-api-key` (api-key)

### POST /ip-info — IP Geolocation

Get comprehensive location and network data for an IP

Returns detailed geolocation including city, region, country, coordinates, timezone, ISP, and ASN information.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `ip` | string | yes | IPv4 or IPv6 address | `8.8.8.8` |
| `reverse_lookup` | boolean | no | Include reverse DNS | `true` |

**Example request body:**
```json
{
  "ip": "8.8.8.8",
  "reverse_lookup": true
}
```

**Example response:**
```json
{
  "valid": true,
  "ip": "8.8.8.8",
  "hostname": "dns.google",
  "city": "Mountain View",
  "region": "California",
  "region-code": "CA",
  "country": "United States",
  "country-code": "US",
  "country-code3": "USA",
  "currency-code": "USD",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "timezone": {
    "id": "America/Los_Angeles",
    "name": "Pacific Daylight Time",
    "abbr": "PDT",
    "offset": "-07:00"
  },
  "isp": "Google LLC",
  "asn": 15169,
  "as-org": "Google LLC",
  "as-domain": "google.com",
  "continent-code": "NA",
  "is-hosting": true,
  "is-mobile": false
}
```

### POST /geocode-address — Geocode Address

Convert street addresses to geographic coordinates

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `address` | string | yes | Full street address | `1600 Amphitheatre Parkway, Mountain View, CA` |
| `country_code` | string | no | ISO country code hint | `US` |
| `language` | string | no | Response language | `en` |
| `fuzzy_search` | boolean | no | Allow fuzzy matching | `true` |

**Example request body:**
```json
{
  "address": "1600 Amphitheatre Parkway, Mountain View, CA",
  "country_code": "US"
}
```

**Example response:**
```json
{
  "found": true,
  "locations": [
    {
      "address": "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
      "address-components": {
        "street-number": "1600",
        "street": "Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "California",
        "postal-code": "94043",
        "country": "United States"
      },
      "latitude": 37.4220656,
      "longitude": -122.0862784,
      "location-type": "address",
      "timezone-id": "America/Los_Angeles"
    }
  ]
}
```

---

## Imaging Tools

QR code generation and image processing

- Base URL: `https://secure.utilitypro.eu/api/v1/imaging-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Professional and Enterprise plans only
- Binary image responses

### POST /qr-code — QR Code Generator

Generate QR codes from text or URLs

Creates customizable QR code images (PNG) with configurable size and colors.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `content` | string | yes | Text or URL to encode | `https://example.com` |
| `width` | number | no | Width in pixels (max 1024) | `256` |
| `height` | number | no | Height in pixels (max 1024) | `256` |
| `fg_color` | string | no | Foreground color (hex) | `#000000` |
| `bg_color` | string | no | Background color (hex) | `#ffffff` |

**Example request body:**
```json
{
  "content": "https://example.com",
  "width": 256,
  "height": 256
}
```

**Example response:**
```json
{
  "note": "Returns binary PNG image",
  "contentType": "image/png"
}
```

Notes:
- Response is binary PNG
- Use --output with cURL to save file

### POST /image-resize — Image Resize

Resize images to specified dimensions

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `image_url` | string | yes | URL of source image | `https://example.com/image.jpg` |
| `width` | number | yes | Target width in pixels | `800` |
| `height` | number | no | Target height in pixels | `600` |
| `format` | string | no | Output format (png, jpg, gif, webp) | `png` |
| `resize_mode` | string | no | scale, crop, or pad | `scale` |
| `bg_color` | string | no | Background color for padding | `transparent` |

**Example request body:**
```json
{
  "image_url": "https://example.com/image.jpg",
  "width": 800,
  "height": 600,
  "format": "png"
}
```

**Example response:**
```json
{
  "note": "Returns binary image",
  "contentType": "image/png"
}
```

### POST /image-watermark — Image Watermark

Add watermarks to images

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `image_url` | string | yes | URL of source image | `https://example.com/photo.jpg` |
| `watermark_url` | string | yes | URL of watermark image | `https://example.com/logo.png` |
| `opacity` | number | no | Watermark opacity 0-100 | `50` |
| `position` | string | no | Position: center, top-left, top-right, bottom-left, bottom-right | `bottom-right` |
| `width` | number | no | Output width | `1920` |
| `height` | number | no | Output height | `1080` |
| `format` | string | no | Output format | `png` |

**Example request body:**
```json
{
  "image_url": "https://example.com/photo.jpg",
  "watermark_url": "https://example.com/logo.png",
  "opacity": 50,
  "position": "bottom-right"
}
```

**Example response:**
```json
{
  "note": "Returns binary image",
  "contentType": "image/png"
}
```

### POST /html-render — HTML Render

Render HTML/CSS to image

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `content` | string | yes | HTML content or URL | `<h1>Hello World</h1>` |
| `width` | number | no | Viewport width | `1024` |
| `height` | number | no | Viewport height | `768` |
| `format` | string | no | Output format (png, jpg, pdf) | `png` |
| `delay` | number | no | Delay before capture (ms) | `1000` |
| `css_url` | string | no | External CSS URL | `https://example.com/style.css` |

**Example request body:**
```json
{
  "content": "<h1 style=\"color: blue;\">Hello World</h1>",
  "width": 800,
  "height": 600,
  "format": "png"
}
```

**Example response:**
```json
{
  "note": "Returns binary image/PDF",
  "contentType": "image/png"
}
```

---

## Telephony & SMS

Phone verification, SMS sending, and HLR lookups

- Base URL: `https://secure.utilitypro.eu/api/v1/telephony-tools`
- Auth: `x-api-key` (api-key)

### POST /phone-verify — Phone Verify

Initiate automated verification call with spoken code

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `number` | string | yes | Phone number in E.164 format | `+14158586273` |
| `security_code` | string | no | Custom code (auto-generated if not provided) | `123456` |
| `country_code` | string | no | ISO 2-letter country code | `US` |
| `language_code` | string | no | Voice language | `en` |
| `code_length` | number | no | Length of generated code (4-8) | `6` |
| `playback_delay` | number | no | Delay between code digits (ms) | `500` |

**Example request body:**
```json
{
  "number": "+14158586273",
  "code_length": 6
}
```

**Example response:**
```json
{
  "calling": true,
  "number-valid": true,
  "security-code": "847291"
}
```

### POST /sms-verify — SMS Verify

Send SMS verification code

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `number` | string | yes | Phone number in E.164 format | `+14158586273` |
| `security_code` | string | no | Custom code (auto-generated if not provided) | `123456` |
| `brand_name` | string | no | Brand name in SMS | `MyApp` |
| `country_code` | string | no | ISO 2-letter country code | `US` |
| `language_code` | string | no | SMS language | `en` |
| `code_length` | number | no | Length of generated code | `5` |

**Example request body:**
```json
{
  "number": "+14158586273",
  "brand_name": "MyApp"
}
```

**Example response:**
```json
{
  "sent": true,
  "number-valid": true,
  "security-code": "84729"
}
```

### POST /verify-security-code — Verify Security Code

Verify code sent via phone-verify or sms-verify

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `security_code` | string | yes | Code entered by user | `847291` |
| `limit_by` | string | yes | Phone number from original verification | `+14158586273` |

**Example request body:**
```json
{
  "security_code": "847291",
  "limit_by": "+14158586273"
}
```

**Example response:**
```json
{
  "verified": true
}
```

### POST /hlr-lookup — HLR Lookup

Check mobile number validity via HLR lookup

Home Location Register lookup to check if mobile number is active, ported, or disconnected.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `number` | string | yes | Phone number in E.164 format | `+14158586273` |
| `country_code` | string | no | ISO 2-letter country code | `US` |

**Example request body:**
```json
{
  "number": "+14158586273"
}
```

**Example response:**
```json
{
  "number-valid": true,
  "international-number": "+14158586273",
  "local-number": "(415) 858-6273",
  "country": "United States",
  "country-code": "US",
  "is-mobile": true,
  "mobile-network": "T-Mobile",
  "mobile-network-code": "310260",
  "is-ported": false,
  "is-roaming": false,
  "is-present": true,
  "hlr-lookup-status": "ok"
}
```

### POST /send-sms — Send SMS

Send SMS messages to one or multiple recipients

Send transactional or marketing SMS. Supports bulk sending to multiple recipients.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `recipients` | string | yes | Phone number(s), comma or space-separated | `+971521234567, +971509876543` |
| `message` | string | yes | SMS message content | `Your verification code is 123456` |
| `sender_id` | string | no | Approved sender ID | `MyBrand` |

**Example request body:**
```json
{
  "recipients": "+971521234567, +971509876543",
  "message": "Hello from UtilityPro!",
  "sender_id": "MyBrand"
}
```

**Example response:**
```json
{
  "success": true,
  "total_recipients": 2,
  "messages_sent": 2,
  "results": [
    {
      "recipient": "+971521234567",
      "status": "sent",
      "message_id": "msg_abc123"
    },
    {
      "recipient": "+971509876543",
      "status": "sent",
      "message_id": "msg_def456"
    }
  ]
}
```

---

## Blockchain Tools

Multi-chain wallet validation, transaction lookup, and balance queries

- Base URL: `https://secure.utilitypro.eu/api/v1/blockchain-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Supports Bitcoin, Ethereum, Polygon, BSC, Tron, Solana

### POST /validate-address — Validate Address

Validate wallet address format for any supported chain

Validates address format using chain-specific regex patterns. Can auto-detect which chain(s) an address belongs to.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `address` | string | yes | Wallet address to validate | `0x742d35Cc6634C0532925a3b844Bc9e7595f14c` |
| `chain` | string | no | Blockchain: bitcoin, ethereum, polygon, bsc, tron, solana | `ethereum` |

**Example request body:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c",
  "chain": "ethereum"
}
```

**Example response:**
```json
{
  "valid": true,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c",
  "chain": "ethereum",
  "format": "valid"
}
```

Notes:
- If chain is omitted, auto-detects matching chains
- Supports: bitcoin, ethereum, polygon, bsc, tron, solana

### POST /transaction — Get Transaction

Fetch detailed transaction data for any chain with optional fiat conversion

Retrieves full transaction details including sender, recipient, value, fees, and status. Use the optional fiat parameter to get fees and values converted to USD, EUR, or other fiat currencies using live exchange rates.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `txHash` | string | yes | Transaction hash | `0x...` |
| `chain` | string | yes | Blockchain network (bitcoin, ethereum, polygon, bsc, tron, solana) | `ethereum` |
| `fiat` | string | no | Fiat currency for price conversion (usd, eur, gbp, etc.) | `usd` |

**Example request body:**
```json
{
  "txHash": "0xabc123...",
  "chain": "ethereum",
  "fiat": "usd"
}
```

**Example response:**
```json
{
  "found": true,
  "chain": "ethereum",
  "txHash": "0xabc123...",
  "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c",
  "to": "0x1234567890abcdef1234567890abcdef12345678",
  "value": 1.5,
  "valueSymbol": "ETH",
  "valueWei": "0x14d1120d7b160000",
  "gasPrice": 25.5,
  "gasUsed": 21000,
  "gasFee": 0.00053,
  "feeSymbol": "ETH",
  "blockNumber": 18500000,
  "status": "success",
  "nonce": 42,
  "fiatPrice": {
    "currency": "USD",
    "pricePerCoin": 3250.5,
    "feeInFiat": 1.72,
    "valueInFiat": 4875.75
  }
}
```

Notes:
- Fees are always in the native token (TRX, ETH, BNB, SOL, etc.)
- Use fiat parameter to get live USD/EUR/GBP conversion
- fiatPrice object only included when fiat parameter is provided

### POST /balance — Get Balance

Get native token balance for a wallet address

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `address` | string | yes | Wallet address | `0x742d35Cc6634C0532925a3b844Bc9e7595f14c` |
| `chain` | string | yes | Blockchain network | `ethereum` |

**Example request body:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c",
  "chain": "ethereum"
}
```

**Example response:**
```json
{
  "chain": "ethereum",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c",
  "balance": 2.5,
  "balanceWei": "0x22b1c8c1227a0000",
  "symbol": "ETH"
}
```

### POST /transactions — Get Transaction History

Fetch recent transactions for a wallet address

Returns the most recent transactions for a wallet across any supported chain. For Tron, includes both native TRX transfers and TRC10/TRC20 token transfers with full token details.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `address` | string | yes | Wallet address | `0x742d35Cc6634C0532925a3b844Bc9e7595f14c` |
| `chain` | string | yes | Blockchain network | `ethereum` |
| `limit` | number | no | Number of transactions to return (default: 10, max: 100) | `10` |

**Example request body:**
```json
{
  "address": "TWndwV1KHa5mfv6fisaTYcn83n5xHc66Xn",
  "chain": "tron",
  "limit": 10
}
```

**Example response:**
```json
{
  "chain": "tron",
  "address": "TWndwV1KHa5mfv6fisaTYcn83n5xHc66Xn",
  "transactions": [
    {
      "hash": "0xabc123...",
      "from": "TAddr1...",
      "to": "TAddr2...",
      "value": 100,
      "type": "TransferContract",
      "tokenSymbol": "TRX",
      "tokenType": "native",
      "timestamp": 1705323000000
    },
    {
      "hash": "0xdef456...",
      "from": "TAddr1...",
      "to": "TAddr2...",
      "value": 50.5,
      "type": "TriggerSmartContract",
      "tokenType": "TRC20",
      "tokenSymbol": "USDT",
      "tokenName": "Tether USD",
      "tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "tokenDecimals": 6,
      "timestamp": 1705322000000
    }
  ],
  "count": 2
}
```

Notes:
- Default limit is 10, maximum is 100
- Transactions are returned newest first
- All chains now include tokenSymbol, tokenType, and tokenAddress where applicable
- ETH/Polygon: ERC20/ERC721/ERC1155 tokens with full metadata
- BSC: BEP20 tokens with symbol, name, address, decimals
- Tron: TRC10/TRC20 tokens with full token info
- Solana: SPL tokens with mint address and decimals
- Bitcoin: Native BTC only (no token standard)

### POST /gas — Get Gas Prices

Get current gas/fee estimates for a blockchain

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `chain` | string | yes | Blockchain network | `ethereum` |

**Example request body:**
```json
{
  "chain": "ethereum"
}
```

**Example response:**
```json
{
  "chain": "ethereum",
  "gasPrice": 25.5,
  "unit": "gwei",
  "estimates": {
    "slow": 20.4,
    "standard": 25.5,
    "fast": 30.6
  },
  "baseFee": 22.3
}
```

### POST /watch — Watch Wallet

Register wallet for real-time webhook notifications

Premium feature. Receive POST notifications to your webhook URL when transactions occur on monitored addresses.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `address` | string | yes | Wallet address to monitor | `0x742d35Cc6634C0532925a3b844Bc9e7595f14c` |
| `chain` | string | yes | Blockchain network | `ethereum` |
| `webhookUrl` | string | yes | Your webhook endpoint URL | `https://yoursite.com/webhook` |

**Example request body:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c",
  "chain": "ethereum",
  "webhookUrl": "https://yoursite.com/webhook"
}
```

**Example response:**
```json
{
  "success": true,
  "message": "Webhook registration queued",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c",
  "chain": "ethereum",
  "webhookUrl": "https://yoursite.com/webhook",
  "note": "You will receive POST requests to your webhook URL when transactions occur"
}
```

Notes:
- Premium tier required
- Contact support to enable
- Webhook receives JSON payloads

---

## Blockchain Compliance

AML/CFT risk scoring for blockchain transactions, addresses, and wallets

- Base URL: `https://secure.utilitypro.eu/api/v1/compliance-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Powered by Scorechain
- Supports 16+ blockchains
- Risk scores from 1 (critical) to 100 (no risk)

### POST /score-transaction — Score Transaction

Get AML/CFT risk score for a blockchain transaction by hash

Analyses a blockchain transaction using Scorechain's compliance engine and returns a risk score (1 = critical risk, 100 = no risk), severity level, counterparty breakdown, entity identification, and triggered risk indicators. Supports ASSIGNED, INCOMING, OUTGOING, or FULL analysis types.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `hash` | string | yes | The transaction hash to analyse | `0x6af2077627203fa96939c7866e59835b3c0ff97ec73da95d2c8cc37291335650` |
| `chain` | string | yes | Blockchain network (bitcoin, ethereum, polygon, bsc, tron, solana, litecoin, dogecoin, ripple, avalanche, arbitrum, optimism, base, stellar, tezos, ton) | `ethereum` |
| `analysis_type` | string | no | Analysis depth: ASSIGNED (entity-only), INCOMING (source of funds), OUTGOING (destination), FULL (complete) | `INCOMING` |
| `coin` | string | no | Specific coin/token to analyse (default ALL) | `ALL` |
| `depth` | integer | no | Max hop depth for tracing (UTXO: up to 100, account-based: up to 6) | `3` |

**Example request body:**
```json
{
  "hash": "0x6af2077627203fa96939c7866e59835b3c0ff97ec73da95d2c8cc37291335650",
  "chain": "ethereum",
  "analysis_type": "INCOMING"
}
```

**Example response:**
```json
{
  "transaction_hash": "0x6af207...",
  "chain": "ethereum",
  "blockchain": "ETHEREUM",
  "analysis_type": "INCOMING",
  "scoring": {
    "overall_score": 75,
    "severity": "LOW_RISK",
    "assigned": {
      "score": 75,
      "severity": "LOW_RISK"
    },
    "incoming": {
      "score": 75,
      "severity": "LOW_RISK",
      "counterparties": [
        {
          "address": "0x31oSG...",
          "name": "Binance",
          "type": "Exchange",
          "countries": [
            "Cayman Islands"
          ],
          "score": 80,
          "severity": "LOW_RISK",
          "percentage": 100,
          "amount_usd": 15230.5
        }
      ]
    },
    "outgoing": null
  },
  "risk_indicators": [
    {
      "type": "ENTITY_TYPE",
      "parameters": {
        "referenceName": "Exchange",
        "threshold": 30
      }
    }
  ],
  "entity": {
    "name": "Binance",
    "type": "Exchange",
    "countries": [
      "Cayman Islands"
    ]
  },
  "provider": "scorechain"
}
```

Notes:
- Score range: 1 (critical risk) to 100 (no risk)
- Severity levels: CRITICAL_RISK, HIGH_RISK, MEDIUM_RISK, LOW_RISK, NO_RISK

### POST /score-address — Score Address

Get AML/CFT risk score for a blockchain address

Analyses a blockchain address and returns a comprehensive risk profile including entity identification, counterparty exposure, and custom risk indicators. Default analysis type is FULL for complete incoming + outgoing fund flow analysis.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `address` | string | yes | The blockchain address to analyse | `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` |
| `chain` | string | yes | Blockchain network | `ethereum` |
| `analysis_type` | string | no | Analysis depth (default FULL) | `FULL` |
| `coin` | string | no | Specific coin/token (default ALL) | `ALL` |
| `depth` | integer | no | Max hop depth for tracing | `3` |

**Example request body:**
```json
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "analysis_type": "FULL"
}
```

**Example response:**
```json
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "blockchain": "ETHEREUM",
  "analysis_type": "FULL",
  "scoring": {
    "overall_score": 90,
    "severity": "NO_RISK",
    "assigned": {
      "score": 90,
      "severity": "NO_RISK"
    },
    "incoming": {
      "score": 85,
      "severity": "LOW_RISK",
      "counterparties": []
    },
    "outgoing": {
      "score": 92,
      "severity": "NO_RISK",
      "counterparties": []
    }
  },
  "risk_indicators": [],
  "entity": {
    "name": "Vitalik Buterin",
    "type": "Individual",
    "countries": []
  },
  "provider": "scorechain"
}
```

Notes:
- Best for KYC/KYW (Know Your Wallet) checks
- FULL analysis covers both fund sources and destinations

### POST /score-wallet — Score Wallet Cluster

Get AML/CFT risk score for a wallet cluster by reference address

Analyses a wallet cluster (group of addresses controlled by the same entity) using a reference address. Returns aggregated risk scoring across the entire wallet, including top counterparties and risk indicators.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `address` | string | yes | Reference address of the wallet cluster | `1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa` |
| `chain` | string | yes | Blockchain network | `bitcoin` |
| `analysis_type` | string | no | Analysis depth (default FULL) | `FULL` |
| `coin` | string | no | Specific coin/token (default ALL) | `MAIN` |
| `depth` | integer | no | Max hop depth for tracing | `5` |

**Example request body:**
```json
{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "chain": "bitcoin",
  "analysis_type": "FULL"
}
```

**Example response:**
```json
{
  "wallet_reference_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "chain": "bitcoin",
  "blockchain": "BITCOIN",
  "analysis_type": "FULL",
  "scoring": {
    "overall_score": 95,
    "severity": "NO_RISK",
    "assigned": {
      "score": 95,
      "severity": "NO_RISK"
    },
    "incoming": {
      "score": 95,
      "severity": "NO_RISK",
      "counterparties": []
    },
    "outgoing": null
  },
  "risk_indicators": [],
  "entity": {
    "name": "Satoshi Nakamoto",
    "type": "Individual",
    "countries": []
  },
  "provider": "scorechain"
}
```

Notes:
- Wallet clustering groups addresses owned by the same entity
- Top 10 counterparties returned per direction

### GET /supported-chains — List Supported Chains

List all blockchains supported for compliance scoring

**Example response:**
```json
{
  "supported_chains": [
    "bitcoin",
    "ethereum",
    "polygon",
    "bsc",
    "tron",
    "solana",
    "litecoin",
    "dogecoin",
    "ripple",
    "avalanche",
    "arbitrum",
    "optimism",
    "base",
    "stellar",
    "tezos",
    "ton"
  ]
}
```

---

## Email API

Transactional email sending with custom domain support

- Base URL: `https://secure.utilitypro.eu/api/v1/email`
- Auth: `x-api-key` (api-key)

### POST /send — Send Email

Send transactional emails via your verified domain

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `from` | string | yes | Sender email (must be from verified domain) | `notifications@yourdomain.com` |
| `to` | string | string[] | yes | Recipient email(s) | `customer@example.com` |
| `subject` | string | yes | Email subject line | `Order Confirmation` |
| `html` | string | no | HTML body content | `<h1>Thank you!</h1>` |
| `text` | string | no | Plain text body | `Thank you for your order.` |
| `cc` | string | string[] | no | CC recipient(s) | `copy@example.com` |
| `bcc` | string | string[] | no | BCC recipient(s) | `archive@example.com` |
| `reply_to` | string | no | Reply-to address | `support@yourdomain.com` |

**Example request body:**
```json
{
  "from": "notifications@yourdomain.com",
  "to": "customer@example.com",
  "subject": "Order Confirmation",
  "html": "<h1>Thank you for your order!</h1><p>Order #12345 confirmed.</p>"
}
```

**Example response:**
```json
{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "resend_id": "re_abc123xyz"
}
```

### POST /domains — Add Domain

Register a custom sending domain

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `domain` | string | yes | Domain to add | `mail.yourdomain.com` |

**Example request body:**
```json
{
  "domain": "mail.yourdomain.com"
}
```

**Example response:**
```json
{
  "success": true,
  "id": "dom_abc123",
  "domain": "mail.yourdomain.com",
  "status": "pending",
  "dns_records": [
    {
      "type": "TXT",
      "name": "_dmarc",
      "value": "v=DMARC1; p=none;",
      "priority": null
    },
    {
      "type": "MX",
      "name": "mail",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "priority": 10
    },
    {
      "type": "TXT",
      "name": "mail",
      "value": "v=spf1 include:amazonses.com ~all",
      "priority": null
    }
  ]
}
```

### GET /domains — List Domains

List all registered email domains with status

**Example response:**
```json
{
  "success": true,
  "domains": [
    {
      "id": "dom_abc123",
      "domain": "mail.yourdomain.com",
      "status": "verified",
      "created_at": "2024-01-15T00:00:00Z",
      "verified_at": "2024-01-15T02:30:00Z"
    }
  ]
}
```

### POST /domains/verify — Verify Domain

Trigger DNS verification check

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `domain_id` | string | yes | Domain ID to verify | `dom_abc123` |

**Example request body:**
```json
{
  "domain_id": "dom_abc123"
}
```

**Example response:**
```json
{
  "success": true,
  "status": "verified",
  "verified_at": "2024-01-15T02:30:00Z"
}
```

### DELETE /domains/:domain_id — Delete Domain

Remove a domain from your account

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `domain_id` | string | yes | Domain ID (URL param) | `dom_abc123` |

**Example response:**
```json
{
  "success": true,
  "message": "Domain removed successfully"
}
```

---

## SwiftHub

SWIFT payment processing, validation, and message handling

- Base URL: `https://secure.utilitypro.eu/api/v1/swifthub`
- Auth: `Authorization` (jwt)

Notes:
- Requires JWT authentication
- Enterprise feature

### POST /swift-validate — Validate Payment

Validate SWIFT payment before submission

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `creditor_name` | string | yes | Beneficiary name | `ACME Corporation` |
| `creditor_iban` | string | yes | Beneficiary IBAN | `DE89370400440532013000` |
| `creditor_bic` | string | no | Beneficiary BIC/SWIFT | `COBADEFFXXX` |
| `amount` | number | yes | Payment amount | `10000.00` |
| `currency` | string | yes | ISO currency code | `EUR` |
| `remittance_unstructured` | string | no | Payment reference | `Invoice INV-2024-001` |
| `charge_type` | string | no | SHA, OUR, or BEN | `SHA` |
| `purpose_code` | string | no | ISO purpose code | `SALA` |

**Example request body:**
```json
{
  "creditor_name": "ACME Corporation",
  "creditor_iban": "DE89370400440532013000",
  "creditor_bic": "COBADEFFXXX",
  "amount": 10000,
  "currency": "EUR",
  "remittance_unstructured": "Invoice INV-2024-001"
}
```

**Example response:**
```json
{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "code": "W001",
      "field": "purpose_code",
      "message": "Purpose code recommended for EUR payments"
    }
  ]
}
```

### POST /swift-payments — Create Payment

Create and submit a new SWIFT payment

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `creditor_name` | string | yes | Beneficiary name | `ACME Corporation` |
| `creditor_iban` | string | yes | Beneficiary IBAN | `DE89370400440532013000` |
| `creditor_bic` | string | no | Beneficiary BIC | `COBADEFFXXX` |
| `amount` | number | yes | Payment amount | `10000.00` |
| `currency` | string | yes | ISO currency code | `EUR` |
| `charge_type` | string | no | SHA, OUR, or BEN | `SHA` |
| `purpose_code` | string | no | ISO purpose code | `SALA` |
| `remittance_unstructured` | string | no | Payment reference (max 140 chars) | `Invoice INV-2024-001` |
| `requested_execution_date` | string | no | ISO date for execution | `2024-12-15` |

**Example request body:**
```json
{
  "creditor_name": "ACME Corporation",
  "creditor_iban": "DE89370400440532013000",
  "creditor_bic": "COBADEFFXXX",
  "amount": 10000,
  "currency": "EUR",
  "remittance_unstructured": "Invoice INV-2024-001",
  "requested_execution_date": "2024-12-15"
}
```

**Example response:**
```json
{
  "success": true,
  "payment_id": "pmt_abc123xyz",
  "uetr": "550e8400-e29b-41d4-a716-446655440000",
  "status": "validated",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### GET /swift-payments/:id — Get Payment Details

Retrieve payment status and history

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `id` | string | yes | Payment ID (URL param) | `pmt_abc123xyz` |

**Example response:**
```json
{
  "id": "pmt_abc123xyz",
  "uetr": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "creditor_name": "ACME Corporation",
  "creditor_iban": "DE89370400440532013000",
  "amount": 10000,
  "currency": "EUR",
  "created_at": "2024-01-15T10:30:00Z",
  "validated_at": "2024-01-15T10:30:05Z",
  "sent_at": "2024-01-15T10:35:00Z",
  "events": [
    {
      "event": "created",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "event": "validated",
      "timestamp": "2024-01-15T10:30:05Z"
    },
    {
      "event": "submitted",
      "timestamp": "2024-01-15T10:32:00Z"
    },
    {
      "event": "sent",
      "timestamp": "2024-01-15T10:35:00Z"
    }
  ]
}
```

### POST /swift-cancel — Cancel Payment

Request cancellation of a pending payment

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `payment_id` | string | yes | Payment ID to cancel | `pmt_abc123xyz` |
| `reason` | string | yes | Cancellation reason | `Duplicate payment` |

**Example request body:**
```json
{
  "payment_id": "pmt_abc123xyz",
  "reason": "Duplicate payment"
}
```

**Example response:**
```json
{
  "success": true,
  "payment_id": "pmt_abc123xyz",
  "status": "cancellation_requested",
  "message": "Cancellation request submitted"
}
```

Notes:
- Not all payments can be cancelled
- Success depends on payment status

### POST /swift-repair — Repair Payment

Correct and resubmit a rejected payment

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `payment_id` | string | yes | Payment ID to repair | `pmt_abc123xyz` |
| `corrections` | object | yes | Fields to correct | `{ "creditor_name": "ACME Corp Ltd" }` |
| `reason` | string | no | Repair reason | `Corrected beneficiary name` |

**Example request body:**
```json
{
  "payment_id": "pmt_abc123xyz",
  "corrections": {
    "creditor_name": "ACME Corp Ltd"
  },
  "reason": "Corrected beneficiary name"
}
```

**Example response:**
```json
{
  "success": true,
  "payment_id": "pmt_abc123xyz",
  "status": "validated",
  "message": "Payment repaired and revalidated"
}
```

---

## VAT Validation

EU VAT number validation and company lookup

- Base URL: `https://secure.utilitypro.eu/api/v1/vat-validation`
- Auth: `x-api-key` (api-key)

### POST / — Validate VAT Number

Validate EU VAT numbers and retrieve company information

Validates VAT number format and checks against EU VIES database. Returns company registration details.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `vat_number` | string | yes | VAT number with country prefix | `DE123456789` |
| `country_code` | string | no | ISO 2-letter country code (optional if in VAT number) | `DE` |

**Example request body:**
```json
{
  "vat_number": "DE123456789"
}
```

**Example response:**
```json
{
  "valid": true,
  "vat_number": "DE123456789",
  "country_code": "DE",
  "country": "Germany",
  "company_name": "Example GmbH",
  "company_address": "Musterstraße 1, 10115 Berlin, Germany",
  "request_date": "2024-01-15T10:30:00Z"
}
```

---

## KYB / Business Registry

Global Legal Entity Identifier (LEI) lookup and company registry search via GLEIF

- Base URL: `https://secure.utilitypro.eu/api/v1/kyb-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Powered by GLEIF
- No third-party API key required

### GET /lei/{lei} — Lookup LEI Record

Fetch the full Legal Entity Identifier record from GLEIF

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `lei` | string | yes | 20-character LEI code | `529900T8BM49AURSDO55` |

**Example response:**
```json
{
  "found": true,
  "lei": "529900T8BM49AURSDO55",
  "legal_name": "GLEIF",
  "jurisdiction": "CH",
  "provider": "gleif"
}
```

### GET /search — Search Legal Entities

Search GLEIF by legal name, optionally filtered by country

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `q` | string | yes | Search term (legal name) |  |
| `country` | string | no | ISO-3166-1 alpha-2 country code |  |
| `limit` | number | no | Max results (1-50, default 10) |  |

**Example request body:**
```json
{
  "q": "Acme",
  "country": "US",
  "limit": 5
}
```

**Example response:**
```json
{
  "query": "Acme",
  "total": 12,
  "results": [],
  "provider": "gleif"
}
```

### GET /fuzzy — Fuzzy Name Suggestions

Autocomplete legal entity names with fuzzy matching

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `q` | string | yes | Partial name |  |

**Example response:**
```json
{
  "query": "Acm",
  "suggestions": [],
  "provider": "gleif"
}
```

---

## Sanctions & PEP Screening

Screen names against OFAC SDN, EU, UN, UK and global PEP lists

- Base URL: `https://secure.utilitypro.eu/api/v1/sanctions-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Powered by OpenSanctions
- Includes consolidated OFAC SDN feed
- /entity/{id} requires an OpenSanctions data subscription — /screen, /ofac-screen and /search are available on all plans

### POST /screen — Screen Name (All Lists)

Screen a person or company against the consolidated OpenSanctions dataset (OFAC, EU, UN, UK, PEPs and more).

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `name` | string | yes | Full name to screen |  |
| `schema` | string | no | "Person" (default) or "Company" |  |
| `country` | string | no | ISO country hint to refine match |  |
| `birth_date` | string | no | YYYY-MM-DD for persons |  |
| `threshold` | number | no | Match score threshold (0-1, default 0.7) |  |
| `limit` | number | no | Max results returned (default 5) |  |

**Example request body:**
```json
{
  "name": "Vladimir Putin",
  "schema": "Person",
  "threshold": 0.7
}
```

**Example response:**
```json
{
  "name": "Vladimir Putin",
  "match_count": 1,
  "is_match": true,
  "best_score": 1,
  "results": [],
  "provider": "opensanctions"
}
```

### POST /ofac-screen — Screen Against OFAC SDN

Restrict screening to the US OFAC SDN list specifically.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `name` | string | yes | Full name |  |
| `schema` | string | no | "Person" or "Company" |  |
| `threshold` | number | no | 0-1, default 0.7 |  |

**Example request body:**
```json
{
  "name": "John Doe"
}
```

**Example response:**
```json
{
  "name": "John Doe",
  "list": "OFAC SDN",
  "match_count": 0,
  "is_match": false,
  "results": [],
  "provider": "opensanctions"
}
```

### GET /search — Free-text Search

Search across sanction datasets

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `q` | string | yes | Search query |  |
| `dataset` | string | no | Dataset (default "default") |  |
| `schema` | string | no | Entity schema |  |

**Example response:**
```json
{
  "query": "Acme",
  "total": 0,
  "results": [],
  "provider": "opensanctions"
}
```

### GET /entity/{id} — Get Entity Detail

Fetch the full record for a sanctioned entity by id. Requires an OpenSanctions data subscription on the account; contact support@utilitypro.eu to enable.

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `id` | string | yes | Entity id returned by /screen or /search |  |

**Example response:**
```json
{
  "id": "NK-...",
  "caption": "...",
  "provider": "opensanctions"
}
```

---

## Banking Calendar

Public holidays and business-day arithmetic for settlement and SLA calculations

- Base URL: `https://secure.utilitypro.eu/api/v1/calendar-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Powered by Nager.Date

### GET /holidays/{country}/{year} — List Public Holidays

Returns all public holidays for a country and year

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `country` | string | yes | ISO-3166-1 alpha-2 | `DE` |
| `year` | string | yes | YYYY | `2026` |

**Example response:**
```json
{
  "country": "DE",
  "year": 2026,
  "count": 12,
  "holidays": [],
  "provider": "nager.date"
}
```

### GET /is-holiday — Is Business Day

Returns whether a given date is a business day, weekend or holiday

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `country` | string | yes | ISO country |  |
| `date` | string | no | YYYY-MM-DD (default today) |  |

**Example response:**
```json
{
  "country": "DE",
  "date": "2026-12-25",
  "is_business_day": false,
  "is_public_holiday": true,
  "holiday": {
    "name": "Christmas Day"
  },
  "provider": "nager.date"
}
```

### GET /next-business-day — Add Business Days

Skip weekends and holidays to compute settlement dates

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `country` | string | yes | ISO country |  |
| `date` | string | no | Start date (default today) |  |
| `days` | number | no | Business days to add (1-60, default 1) |  |

**Example response:**
```json
{
  "country": "DE",
  "start": "2026-12-24",
  "business_days_added": 2,
  "result": "2026-12-29",
  "skipped": [
    "2026-12-25",
    "2026-12-26",
    "2026-12-27"
  ],
  "provider": "nager.date"
}
```

### GET /supported-countries — Supported Countries

List ISO codes covered by the holidays dataset

**Example response:**
```json
{
  "countries": [
    {
      "countryCode": "DE",
      "name": "Germany"
    }
  ],
  "provider": "nager.date"
}
```

---

## Reference Data

Country reference data, FX rates, and global VAT rate lookup

- Base URL: `https://secure.utilitypro.eu/api/v1/reference-tools`
- Auth: `x-api-key` (api-key)

Notes:
- Country data from mledoze/countries (ISO-3166)
- VAT rates from curated EU table
- FX rates and VAT-number validation via VATComply

### GET /countries — List All Countries

All ISO countries with currencies, languages, calling codes, and region metadata

**Example response:**
```json
{
  "count": 250,
  "countries": [],
  "provider": "mledoze/countries"
}
```

### GET /country/{code} — Country Detail

Look up a country by ISO 2- or 3-letter code

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `code` | string | yes | ISO code | `DE` |

**Example response:**
```json
{
  "found": true,
  "name": "Germany",
  "official_name": "Federal Republic of Germany",
  "cca2": "DE",
  "cca3": "DEU",
  "ccn3": "276",
  "region": "Europe",
  "subregion": "Western Europe",
  "capital": [
    "Berlin"
  ],
  "currencies": [
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€"
    }
  ],
  "languages": [
    "German"
  ],
  "calling_codes": [
    "+49"
  ],
  "flag": "https://flagcdn.com/de.svg",
  "provider": "mledoze/countries"
}
```

### GET /vat-rates/{country} — VAT Rate Lookup

Standard and reduced VAT rates per country (curated EU table)

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `country` | string | no | ISO 2-letter; omit for full table |  |

**Example response:**
```json
{
  "country": "DE",
  "country_name": "Germany",
  "standard_rate": 19,
  "reduced_rates": [
    7
  ],
  "super_reduced_rate": null,
  "parking_rate": null,
  "provider": "utilitypro"
}
```

### GET /fx-rates — Daily FX Rates

Foreign exchange rates relative to a base currency

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `base` | string | no | Base currency (default EUR) |  |
| `symbols` | string | no | Comma-separated target currencies |  |
| `date` | string | no | YYYY-MM-DD for historical rates |  |

**Example response:**
```json
{
  "base": "EUR",
  "date": "2026-05-04",
  "rates": {
    "USD": 1.08,
    "GBP": 0.86
  },
  "provider": "vatcomply"
}
```

### GET /vat-validate — EU VAT Validate

Validate an EU VAT number via VATComply

**Parameters:**

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `vat` | string | yes | VAT number with country prefix | `DE123456789` |

**Example response:**
```json
{
  "country_code": "DE",
  "vat_number": "123456789",
  "valid": true,
  "name": "Acme GmbH",
  "provider": "vatcomply"
}
```