{ "openapi": "3.1.0", "info": { "title": "UtilityPro API", "version": "1.0.0", "description": "FinTech & RegTech API suite by Dataspring Solutions Ltd. Payment validation, banking tools, KYC/KYB, sanctions & PEP screening, device intelligence, blockchain, and more.", "contact": { "name": "UtilityPro", "email": "hello@utilitypro.eu", "url": "https://www.utilitypro.eu" }, "license": { "name": "Commercial" } }, "servers": [ { "url": "https://secure.utilitypro.eu", "description": "Production" } ], "tags": [ { "name": "Payment Validation", "description": "Validate international payment requirements for 147+ countries and currencies" }, { "name": "Data Tools", "description": "Email/phone validation, data cleansing, and fuzzy name matching" }, { "name": "Banking Tools", "description": "IBAN, BIC/SWIFT, IFSC, and BIN/IIN validation and lookup" }, { "name": "Security Tools", "description": "Domain lookup, IP intelligence, blocklist checks, and threat detection" }, { "name": "Device Intelligence", "description": "White-label device fingerprinting, bot detection, VPN/proxy/incognito/tampering signals and visitor history" }, { "name": "Geolocation", "description": "IP geolocation, reverse geocoding, and address validation" }, { "name": "Imaging Tools", "description": "QR code generation and image processing" }, { "name": "Telephony & SMS", "description": "Phone verification, SMS sending, and HLR lookups" }, { "name": "Blockchain Tools", "description": "Multi-chain wallet validation, transaction lookup, and balance queries" }, { "name": "Blockchain Compliance", "description": "AML/CFT risk scoring for blockchain transactions, addresses, and wallets" }, { "name": "Email API", "description": "Transactional email sending with custom domain support" }, { "name": "SwiftHub", "description": "SWIFT payment processing, validation, and message handling" }, { "name": "VAT Validation", "description": "EU VAT number validation and company lookup" }, { "name": "KYB / Business Registry", "description": "Global Legal Entity Identifier (LEI) lookup and company registry search via GLEIF" }, { "name": "Sanctions & PEP Screening", "description": "Screen names against OFAC SDN, EU, UN, UK and global PEP lists" }, { "name": "Banking Calendar", "description": "Public holidays and business-day arithmetic for settlement and SLA calculations" }, { "name": "Reference Data", "description": "Country reference data, FX rates, and global VAT rate lookup" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "paths": { "/api/v1/payment-validation/requirements": { "get": { "tags": [ "Payment Validation" ], "summary": "Get Payment Requirements", "description": "Retrieve payment field requirements for a country and/or currency, optionally filtered by transfer type\n\nReturns 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.\n\nAt least one of country_code or currency_code is required\n\nCombine both for most accurate requirements\n\nUse transfer_type to filter requirements for a specific clearing network (domestic, sepa, international)\n\nOmitting transfer_type returns all requirements unfiltered (backward compatible)\n\nThe response includes available_transfer_types so clients can discover valid options\n\nSEPA is only available for SEPA-zone countries with eligible currencies (EUR, SEK, DKK, CHF, etc.)", "operationId": "payment_GET_requirements", "parameters": [ { "name": "country_code", "in": "query", "required": false, "description": "ISO 2-letter country code", "schema": { "type": "string" }, "example": "DE" }, { "name": "currency_code", "in": "query", "required": false, "description": "ISO 3-letter currency code", "schema": { "type": "string" }, "example": "EUR" }, { "name": "transfer_type", "in": "query", "required": false, "description": "Transfer type to filter requirements: domestic, sepa, or international. Omit to get all requirements.", "schema": { "type": "string" }, "example": "sepa" } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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": [] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/payment-validation/countries": { "get": { "tags": [ "Payment Validation" ], "summary": "List Countries", "description": "Get all supported countries with their ISO codes", "operationId": "payment_GET_countries", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/payment-validation/currencies": { "get": { "tags": [ "Payment Validation" ], "summary": "List Currencies", "description": "Get all supported currencies with their ISO codes", "operationId": "payment_GET_currencies", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/data-tools/email-validate": { "post": { "tags": [ "Data Tools" ], "summary": "Email Validate", "description": "Parse, validate and clean email addresses\n\nValidates email syntax, checks DNS/MX records, detects freemails and disposable emails, and can auto-fix common domain typos.", "operationId": "datatools_POST_email_validate", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to validate", "example": "test@example.com" }, "fix_typos": { "type": "boolean", "description": "Auto-fix common domain typos", "example": "true" } }, "required": [ "email" ] }, "example": { "email": "test@example.com", "fix_typos": true } } } } } }, "/api/v1/data-tools/email-verify": { "post": { "tags": [ "Data Tools" ], "summary": "Email Verify (SMTP)", "description": "Real-time SMTP verification to check email deliverability\n\nPerforms actual SMTP handshake to verify if an email address can receive mail. More thorough than basic validation.\n\nSMTP verification may take 2-5 seconds\n\nSome servers block verification attempts", "operationId": "datatools_POST_email_verify", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to verify", "example": "test@example.com" }, "fix_typos": { "type": "boolean", "description": "Auto-fix common domain typos", "example": "false" } }, "required": [ "email" ] }, "example": { "email": "test@example.com" } } } } } }, "/api/v1/data-tools/phone-validate": { "post": { "tags": [ "Data Tools" ], "summary": "Phone Validate", "description": "Parse, validate and get carrier information for phone numbers\n\nValidates phone number format, determines carrier/network, location, and formats to international/local standards.", "operationId": "datatools_POST_phone_validate", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "Phone number (local or international)", "example": "+14158586273" }, "country_code": { "type": "string", "description": "ISO 2-letter country code for local numbers", "example": "US" }, "ip": { "type": "string", "description": "User IP to determine country", "example": "8.8.8.8" } }, "required": [ "number" ] }, "example": { "number": "+14158586273", "country_code": "US" } } } } } }, "/api/v1/data-tools/bad-word-filter": { "post": { "tags": [ "Data Tools" ], "summary": "Bad Word Filter", "description": "Detect and censor profanity in text content\n\nScans text for profanity, slurs, and inappropriate content. Can censor or flag offensive words.", "operationId": "datatools_POST_bad_word_filter", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "is-bad": false, "bad-words-list": [], "bad-words-total": 0, "censored-content": "This is some clean text" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Text content to filter", "example": "This is some text" }, "censor_character": { "type": "string", "description": "Character to replace bad words", "example": "*" } }, "required": [ "content" ] }, "example": { "content": "This is some clean text", "censor_character": "*" } } } } } }, "/api/v1/data-tools/convert": { "post": { "tags": [ "Data Tools" ], "summary": "Unit Convert", "description": "Convert between units and currencies", "operationId": "datatools_POST_convert", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "valid": true, "result": 91.25, "from-value": 100, "from-type": "USD", "to-type": "EUR", "result-float": 91.25 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_value": { "type": "number", "description": "Value to convert", "example": "100" }, "from_type": { "type": "string", "description": "Source unit/currency", "example": "USD" }, "to_type": { "type": "string", "description": "Target unit/currency", "example": "EUR" } }, "required": [ "from_value", "from_type", "to_type" ] }, "example": { "from_value": 100, "from_type": "USD", "to_type": "EUR" } } } } } }, "/api/v1/data-tools/name-match": { "post": { "tags": [ "Data Tools" ], "summary": "Name Match", "description": "Fuzzy name matching for individuals and corporate entities\n\nAdvanced 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.\n\nIndividual mode: decisions at strong_match (≥0.92), match (≥0.88), review (≥0.80), no_match (<0.80)\n\nCorporate mode: legal suffix normalisation (Ltd/LLC/GmbH/SA/BV/KK etc.), noise word filtering, flat token-set scoring\n\nCorporate mode: decisions at strong_match (≥0.92), match (≥0.85), review (≥0.78), no_match (<0.78)\n\nBatch mode: send 'pairs' array with up to 100 {left_name, right_name} objects; returns results[] with index\n\nTransliteration: Arabic and Cyrillic scripts auto-converted to Latin before matching\n\nConfidence metadata: processing_time_ms and match_quality (high/medium/low) included in every response\n\nHandles honorifics (Mr, Mrs, Dr, Prof, Shri, etc.) in individual mode\n\nFilters low-signal tokens (BIN, BINTI, VON, S/O, D/O, etc.) in individual mode\n\nExpands combined initials (RK → R, K) in individual mode\n\nAutomatically tests first/last name swap in individual mode", "operationId": "datatools_POST_name_match", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "left_name": { "type": "string", "description": "First name to compare (single mode)", "example": "Dr. John Robert Smith" }, "right_name": { "type": "string", "description": "Second name to compare (single mode)", "example": "Smith John R" }, "type": { "type": "string", "description": "Match mode: 'individual' (default) or 'corporate'", "example": "individual" }, "pairs": { "type": "array", "description": "Array of {left_name, right_name, type?} for batch mode (max 100 pairs). Omit left_name/right_name when using pairs.", "example": "[{\"left_name\":\"John Smith\",\"right_name\":\"Jon Smyth\"}]" } }, "required": [ "left_name", "right_name" ] }, "example": { "left_name": "Dr. John Robert Smith", "right_name": "Smith John R", "type": "individual" } } } } } }, "/api/v1/data-tools/disposable-email-check": { "post": { "tags": [ "Data Tools" ], "summary": "Disposable Email Check", "description": "Detect throwaway / temporary email providers", "operationId": "datatools_POST_disposable_email_check", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "email": "foo@mailinator.com", "domain": "mailinator.com", "is_disposable": true, "provider": "disposable-email-domains" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email to check", "example": "foo@mailinator.com" } }, "required": [ "email" ] }, "example": { "email": "foo@mailinator.com" } } } } } }, "/api/v1/data-tools/mx-validate": { "post": { "tags": [ "Data Tools" ], "summary": "MX Record Validation", "description": "Verify a domain (or email domain) has valid MX records", "operationId": "datatools_POST_mx_validate", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain to check" }, "email": { "type": "string", "description": "Or pass an email to extract its domain" } }, "required": [] }, "example": { "domain": "gmail.com" } } } } } }, "/api/v1/banking-tools/iban-lookup": { "post": { "tags": [ "Banking Tools" ], "summary": "IBAN Lookup", "description": "Validate IBAN and retrieve bank details\n\nValidates IBAN structure and checksum, extracts bank and account details, identifies SEPA support.", "operationId": "banking_POST_iban_lookup", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "iban": { "type": "string", "description": "Full IBAN number", "example": "DE89370400440532013000" } }, "required": [ "iban" ] }, "example": { "iban": "DE89370400440532013000" } } } } } }, "/api/v1/banking-tools/bic-lookup": { "post": { "tags": [ "Banking Tools" ], "summary": "BIC/SWIFT Lookup", "description": "Get bank details from BIC/SWIFT code", "operationId": "banking_POST_bic_lookup", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bic": { "type": "string", "description": "BIC/SWIFT code (8 or 11 characters)", "example": "COBADEFFXXX" } }, "required": [ "bic" ] }, "example": { "bic": "COBADEFFXXX" } } } } } }, "/api/v1/banking-tools/ifsc-lookup": { "post": { "tags": [ "Banking Tools" ], "summary": "IFSC Lookup", "description": "Validate Indian Financial System Code (IFSC)", "operationId": "banking_POST_ifsc_lookup", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ifsc": { "type": "string", "description": "IFSC code (11 characters)", "example": "SBIN0001234" } }, "required": [ "ifsc" ] }, "example": { "ifsc": "SBIN0001234" } } } } } }, "/api/v1/banking-tools/bin-lookup": { "post": { "tags": [ "Banking Tools" ], "summary": "BIN Lookup", "description": "Get card issuer information from BIN/IIN number\n\nLooks up card issuer details including bank name, card type (credit/debit), brand (Visa/Mastercard), and country of issue.", "operationId": "banking_POST_bin_lookup", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bin_number": { "type": "string", "description": "First 6-8 digits of card number (legacy alias: binNumber)", "example": "45717360" } }, "required": [ "bin_number" ] }, "example": { "bin_number": "45717360" } } } } } }, "/api/v1/security-tools/domain-lookup": { "post": { "tags": [ "Security Tools" ], "summary": "Domain Lookup", "description": "Get DNS and WHOIS information for a domain\n\nRetrieves comprehensive domain information including DNS records, WHOIS data, registrar details, and domain age.", "operationId": "security_POST_domain_lookup", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "description": "Domain name to lookup", "example": "example.com" }, "live": { "type": "boolean", "description": "Force live DNS lookup", "example": "true" } }, "required": [ "host" ] }, "example": { "host": "example.com", "live": true } } } } } }, "/api/v1/security-tools/ip-probe": { "post": { "tags": [ "Security Tools" ], "summary": "IP Probe", "description": "Get detailed IP intelligence and risk scoring\n\nComprehensive IP analysis including geolocation, ISP details, proxy/VPN detection, and threat intelligence.\n\nFraud 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[]).", "operationId": "security_POST_ip_probe", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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": "" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IPv4 or IPv6 address", "example": "8.8.8.8" } }, "required": [ "ip" ] }, "example": { "ip": "8.8.8.8" } } } } } }, "/api/v1/security-tools/ip-blocklist": { "post": { "tags": [ "Security Tools" ], "summary": "IP Blocklist Check", "description": "Check IP against known blocklists and threat databases", "operationId": "security_POST_ip_blocklist", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IPv4 or IPv6 address", "example": "192.168.1.1" }, "vpn_lookup": { "type": "boolean", "description": "Include VPN detection", "example": "true" } }, "required": [ "ip" ] }, "example": { "ip": "8.8.8.8", "vpn_lookup": true } } } } } }, "/api/v1/security-tools/host-reputation": { "post": { "tags": [ "Security Tools" ], "summary": "Host Reputation", "description": "Check host safety score and malware/phishing detection", "operationId": "security_POST_host_reputation", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "description": "Domain or URL to check", "example": "example.com" }, "list_rating": { "type": "number", "description": "Minimum blocklist rating threshold (1-3)", "example": "1" } }, "required": [ "host" ] }, "example": { "host": "example.com", "list_rating": 1 } } } } } }, "/api/v1/security-tools/urlhaus-lookup": { "post": { "tags": [ "Security Tools" ], "summary": "URLhaus Malware Lookup", "description": "Check a URL or host against the abuse.ch URLhaus malware feed\n\nFree service. Optional URLHAUS_AUTH_KEY enables higher quotas.", "operationId": "security_POST_urlhaus_lookup", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "query": "http://example.com/malware.exe", "listed": false, "threat": null, "tags": [], "provider": "abuse.ch/urlhaus" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Full URL to check" }, "host": { "type": "string", "description": "Hostname to check (use either url or host)" } }, "required": [] }, "example": { "url": "http://example.com/malware.exe" } } } } } }, "/api/v1/device-intel-tools/script": { "post": { "tags": [ "Device Intelligence" ], "summary": "Generate Embed Script", "description": "Generate the white-label JavaScript snippet to embed on your website\n\nStep 1 of the integration. Returns a ready-to-paste " } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": {} } } } } }, "/api/v1/device-intel-tools/generatepath": { "get": { "tags": [ "Device Intelligence" ], "summary": "Module Proxy (internal)", "description": "White-label proxy that serves the fingerprinting module to the embedded snippet\n\nCalled 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.\n\nInternal — invoked by the snippet returned from /script.\n\nNo authentication required (public proxy).", "operationId": "device_GET_generatepath", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "_comment": "Returns JavaScript (application/javascript) — not JSON." } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/device-intel-tools/collect": { "post": { "tags": [ "Device Intelligence" ], "summary": "Collect Visitor Data (internal)", "description": "Receives requestId + visitorId from the embedded snippet\n\nCalled 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.\n\nInternal — invoked by the snippet returned from /script.\n\nAuthenticated via the encrypted clientToken, not the x-api-key header.", "operationId": "device_POST_collect", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Per-page-view request ID produced by the fingerprinting module", "example": "req_abc123" }, "visitorId": { "type": "string", "description": "Persistent visitor ID produced by the fingerprinting module", "example": "vst_xyz789" }, "clientToken": { "type": "string", "description": "Encrypted token embedded in the generated snippet — identifies the merchant", "example": "enc_..." } }, "required": [ "requestId", "visitorId", "clientToken" ] }, "example": { "requestId": "req_abc123", "visitorId": "vst_xyz789", "clientToken": "enc_..." } } } } } }, "/api/v1/device-intel-tools/get-info-byrequestid": { "post": { "tags": [ "Device Intelligence" ], "summary": "Get Event by Request ID", "description": "Fetch full fraud intelligence for a single page view\n\nStep 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.\n\nOnly returns data for requestIds that belong to your account — cross-merchant lookups return 404.\n\nCall from your backend so the API key is never exposed to the browser.", "operationId": "device_POST_get_info_byrequestid", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID captured by the embedded snippet for the page view you want to inspect", "example": "req_abc123" } }, "required": [ "requestId" ] }, "example": { "requestId": "req_abc123" } } } } } }, "/api/v1/device-intel-tools/get-visitor-info": { "post": { "tags": [ "Device Intelligence" ], "summary": "Get Visitor History", "description": "Fetch the full history of page views for a single visitor\n\nUse 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).\n\nOnly returns data for visitorIds that have at least one event on your account.", "operationId": "device_POST_get_visitor_info", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "visitorId": "vst_xyz789", "visits": [ { "requestId": "req_abc123", "timestamp": 1736942400000, "ip": "203.0.113.45", "url": "https://yoursite.com/checkout", "confidence": { "score": 0.99 } } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visitorId": { "type": "string", "description": "Persistent visitor ID", "example": "vst_xyz789" } }, "required": [ "visitorId" ] }, "example": { "visitorId": "vst_xyz789" } } } } } }, "/api/v1/device-intel-tools/get-all-device-info-byrange": { "post": { "tags": [ "Device Intelligence" ], "summary": "Get Events by Date Range", "description": "Bulk-export all device events captured within a date range\n\nReturns 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.\n\nEach event in the array counts as one API call against your plan.\n\nKeep ranges narrow (a day or two at a time) for large traffic volumes.", "operationId": "device_POST_get_all_device_info_byrange", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "events": [ { "products": { "identification": { "data": { "visitorId": "vst_xyz789", "requestId": "req_abc123", "ip": "203.0.113.45" } }, "botd": { "data": { "bot": { "result": "notDetected" } } } } } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "startDate": { "type": "string", "description": "ISO-8601 start timestamp (inclusive)", "example": "2025-06-01T00:00:00Z" }, "endDate": { "type": "string", "description": "ISO-8601 end timestamp (inclusive)", "example": "2025-06-10T23:59:59Z" } }, "required": [ "startDate", "endDate" ] }, "example": { "startDate": "2025-06-01T00:00:00Z", "endDate": "2025-06-10T23:59:59Z" } } } } } }, "/api/v1/geolocation-tools/ip-info": { "post": { "tags": [ "Geolocation" ], "summary": "IP Geolocation", "description": "Get comprehensive location and network data for an IP\n\nReturns detailed geolocation including city, region, country, coordinates, timezone, ISP, and ASN information.", "operationId": "geolocation_POST_ip_info", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IPv4 or IPv6 address", "example": "8.8.8.8" }, "reverse_lookup": { "type": "boolean", "description": "Include reverse DNS", "example": "true" } }, "required": [ "ip" ] }, "example": { "ip": "8.8.8.8", "reverse_lookup": true } } } } } }, "/api/v1/geolocation-tools/geocode-address": { "post": { "tags": [ "Geolocation" ], "summary": "Geocode Address", "description": "Convert street addresses to geographic coordinates", "operationId": "geolocation_POST_geocode_address", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Full street address", "example": "1600 Amphitheatre Parkway, Mountain View, CA" }, "country_code": { "type": "string", "description": "ISO country code hint", "example": "US" }, "language": { "type": "string", "description": "Response language", "example": "en" }, "fuzzy_search": { "type": "boolean", "description": "Allow fuzzy matching", "example": "true" } }, "required": [ "address" ] }, "example": { "address": "1600 Amphitheatre Parkway, Mountain View, CA", "country_code": "US" } } } } } }, "/api/v1/imaging-tools/qr-code": { "post": { "tags": [ "Imaging Tools" ], "summary": "QR Code Generator", "description": "Generate QR codes from text or URLs\n\nCreates customizable QR code images (PNG) with configurable size and colors.\n\nResponse is binary PNG\n\nUse --output with cURL to save file", "operationId": "imaging_POST_qr_code", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "note": "Returns binary PNG image", "contentType": "image/png" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Text or URL to encode", "example": "https://example.com" }, "width": { "type": "number", "description": "Width in pixels (max 1024)", "example": "256" }, "height": { "type": "number", "description": "Height in pixels (max 1024)", "example": "256" }, "fg_color": { "type": "string", "description": "Foreground color (hex)", "example": "#000000" }, "bg_color": { "type": "string", "description": "Background color (hex)", "example": "#ffffff" } }, "required": [ "content" ] }, "example": { "content": "https://example.com", "width": 256, "height": 256 } } } } } }, "/api/v1/imaging-tools/image-resize": { "post": { "tags": [ "Imaging Tools" ], "summary": "Image Resize", "description": "Resize images to specified dimensions", "operationId": "imaging_POST_image_resize", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "note": "Returns binary image", "contentType": "image/png" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of source image", "example": "https://example.com/image.jpg" }, "width": { "type": "number", "description": "Target width in pixels", "example": "800" }, "height": { "type": "number", "description": "Target height in pixels", "example": "600" }, "format": { "type": "string", "description": "Output format (png, jpg, gif, webp)", "example": "png" }, "resize_mode": { "type": "string", "description": "scale, crop, or pad", "example": "scale" }, "bg_color": { "type": "string", "description": "Background color for padding", "example": "transparent" } }, "required": [ "image_url", "width" ] }, "example": { "image_url": "https://example.com/image.jpg", "width": 800, "height": 600, "format": "png" } } } } } }, "/api/v1/imaging-tools/image-watermark": { "post": { "tags": [ "Imaging Tools" ], "summary": "Image Watermark", "description": "Add watermarks to images", "operationId": "imaging_POST_image_watermark", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "note": "Returns binary image", "contentType": "image/png" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of source image", "example": "https://example.com/photo.jpg" }, "watermark_url": { "type": "string", "description": "URL of watermark image", "example": "https://example.com/logo.png" }, "opacity": { "type": "number", "description": "Watermark opacity 0-100", "example": "50" }, "position": { "type": "string", "description": "Position: center, top-left, top-right, bottom-left, bottom-right", "example": "bottom-right" }, "width": { "type": "number", "description": "Output width", "example": "1920" }, "height": { "type": "number", "description": "Output height", "example": "1080" }, "format": { "type": "string", "description": "Output format", "example": "png" } }, "required": [ "image_url", "watermark_url" ] }, "example": { "image_url": "https://example.com/photo.jpg", "watermark_url": "https://example.com/logo.png", "opacity": 50, "position": "bottom-right" } } } } } }, "/api/v1/imaging-tools/html-render": { "post": { "tags": [ "Imaging Tools" ], "summary": "HTML Render", "description": "Render HTML/CSS to image", "operationId": "imaging_POST_html_render", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "note": "Returns binary image/PDF", "contentType": "image/png" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "HTML content or URL", "example": "

Hello World

" }, "width": { "type": "number", "description": "Viewport width", "example": "1024" }, "height": { "type": "number", "description": "Viewport height", "example": "768" }, "format": { "type": "string", "description": "Output format (png, jpg, pdf)", "example": "png" }, "delay": { "type": "number", "description": "Delay before capture (ms)", "example": "1000" }, "css_url": { "type": "string", "description": "External CSS URL", "example": "https://example.com/style.css" } }, "required": [ "content" ] }, "example": { "content": "

Hello World

", "width": 800, "height": 600, "format": "png" } } } } } }, "/api/v1/telephony-tools/phone-verify": { "post": { "tags": [ "Telephony & SMS" ], "summary": "Phone Verify", "description": "Initiate automated verification call with spoken code", "operationId": "telephony_POST_phone_verify", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "calling": true, "number-valid": true, "security-code": "847291" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "Phone number in E.164 format", "example": "+14158586273" }, "security_code": { "type": "string", "description": "Custom code (auto-generated if not provided)", "example": "123456" }, "country_code": { "type": "string", "description": "ISO 2-letter country code", "example": "US" }, "language_code": { "type": "string", "description": "Voice language", "example": "en" }, "code_length": { "type": "number", "description": "Length of generated code (4-8)", "example": "6" }, "playback_delay": { "type": "number", "description": "Delay between code digits (ms)", "example": "500" } }, "required": [ "number" ] }, "example": { "number": "+14158586273", "code_length": 6 } } } } } }, "/api/v1/telephony-tools/sms-verify": { "post": { "tags": [ "Telephony & SMS" ], "summary": "SMS Verify", "description": "Send SMS verification code", "operationId": "telephony_POST_sms_verify", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "sent": true, "number-valid": true, "security-code": "84729" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "Phone number in E.164 format", "example": "+14158586273" }, "security_code": { "type": "string", "description": "Custom code (auto-generated if not provided)", "example": "123456" }, "brand_name": { "type": "string", "description": "Brand name in SMS", "example": "MyApp" }, "country_code": { "type": "string", "description": "ISO 2-letter country code", "example": "US" }, "language_code": { "type": "string", "description": "SMS language", "example": "en" }, "code_length": { "type": "number", "description": "Length of generated code", "example": "5" } }, "required": [ "number" ] }, "example": { "number": "+14158586273", "brand_name": "MyApp" } } } } } }, "/api/v1/telephony-tools/verify-security-code": { "post": { "tags": [ "Telephony & SMS" ], "summary": "Verify Security Code", "description": "Verify code sent via phone-verify or sms-verify", "operationId": "telephony_POST_verify_security_code", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "verified": true } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "security_code": { "type": "string", "description": "Code entered by user", "example": "847291" }, "limit_by": { "type": "string", "description": "Phone number from original verification", "example": "+14158586273" } }, "required": [ "security_code", "limit_by" ] }, "example": { "security_code": "847291", "limit_by": "+14158586273" } } } } } }, "/api/v1/telephony-tools/hlr-lookup": { "post": { "tags": [ "Telephony & SMS" ], "summary": "HLR Lookup", "description": "Check mobile number validity via HLR lookup\n\nHome Location Register lookup to check if mobile number is active, ported, or disconnected.", "operationId": "telephony_POST_hlr_lookup", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "Phone number in E.164 format", "example": "+14158586273" }, "country_code": { "type": "string", "description": "ISO 2-letter country code", "example": "US" } }, "required": [ "number" ] }, "example": { "number": "+14158586273" } } } } } }, "/api/v1/telephony-tools/send-sms": { "post": { "tags": [ "Telephony & SMS" ], "summary": "Send SMS", "description": "Send SMS messages to one or multiple recipients\n\nSend transactional or marketing SMS. Supports bulk sending to multiple recipients.", "operationId": "telephony_POST_send_sms", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "string", "description": "Phone number(s), comma or space-separated", "example": "+971521234567, +971509876543" }, "message": { "type": "string", "description": "SMS message content", "example": "Your verification code is 123456" }, "sender_id": { "type": "string", "description": "Approved sender ID", "example": "MyBrand" } }, "required": [ "recipients", "message" ] }, "example": { "recipients": "+971521234567, +971509876543", "message": "Hello from UtilityPro!", "sender_id": "MyBrand" } } } } } }, "/api/v1/blockchain-tools/validate-address": { "post": { "tags": [ "Blockchain Tools" ], "summary": "Validate Address", "description": "Validate wallet address format for any supported chain\n\nValidates address format using chain-specific regex patterns. Can auto-detect which chain(s) an address belongs to.\n\nIf chain is omitted, auto-detects matching chains\n\nSupports: bitcoin, ethereum, polygon, bsc, tron, solana", "operationId": "blockchain_POST_validate_address", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "valid": true, "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c", "chain": "ethereum", "format": "valid" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address to validate", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c" }, "chain": { "type": "string", "description": "Blockchain: bitcoin, ethereum, polygon, bsc, tron, solana", "example": "ethereum" } }, "required": [ "address" ] }, "example": { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c", "chain": "ethereum" } } } } } }, "/api/v1/blockchain-tools/transaction": { "post": { "tags": [ "Blockchain Tools" ], "summary": "Get Transaction", "description": "Fetch detailed transaction data for any chain with optional fiat conversion\n\nRetrieves 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.\n\nFees are always in the native token (TRX, ETH, BNB, SOL, etc.)\n\nUse fiat parameter to get live USD/EUR/GBP conversion\n\nfiatPrice object only included when fiat parameter is provided", "operationId": "blockchain_POST_transaction", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "txHash": { "type": "string", "description": "Transaction hash", "example": "0x..." }, "chain": { "type": "string", "description": "Blockchain network (bitcoin, ethereum, polygon, bsc, tron, solana)", "example": "ethereum" }, "fiat": { "type": "string", "description": "Fiat currency for price conversion (usd, eur, gbp, etc.)", "example": "usd" } }, "required": [ "txHash", "chain" ] }, "example": { "txHash": "0xabc123...", "chain": "ethereum", "fiat": "usd" } } } } } }, "/api/v1/blockchain-tools/balance": { "post": { "tags": [ "Blockchain Tools" ], "summary": "Get Balance", "description": "Get native token balance for a wallet address", "operationId": "blockchain_POST_balance", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "chain": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c", "balance": 2.5, "balanceWei": "0x22b1c8c1227a0000", "symbol": "ETH" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c" }, "chain": { "type": "string", "description": "Blockchain network", "example": "ethereum" } }, "required": [ "address", "chain" ] }, "example": { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c", "chain": "ethereum" } } } } } }, "/api/v1/blockchain-tools/transactions": { "post": { "tags": [ "Blockchain Tools" ], "summary": "Get Transaction History", "description": "Fetch recent transactions for a wallet address\n\nReturns 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.\n\nDefault limit is 10, maximum is 100\n\nTransactions are returned newest first\n\nAll chains now include tokenSymbol, tokenType, and tokenAddress where applicable\n\nETH/Polygon: ERC20/ERC721/ERC1155 tokens with full metadata\n\nBSC: BEP20 tokens with symbol, name, address, decimals\n\nTron: TRC10/TRC20 tokens with full token info\n\nSolana: SPL tokens with mint address and decimals\n\nBitcoin: Native BTC only (no token standard)", "operationId": "blockchain_POST_transactions", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c" }, "chain": { "type": "string", "description": "Blockchain network", "example": "ethereum" }, "limit": { "type": "number", "description": "Number of transactions to return (default: 10, max: 100)", "example": "10" } }, "required": [ "address", "chain" ] }, "example": { "address": "TWndwV1KHa5mfv6fisaTYcn83n5xHc66Xn", "chain": "tron", "limit": 10 } } } } } }, "/api/v1/blockchain-tools/gas": { "post": { "tags": [ "Blockchain Tools" ], "summary": "Get Gas Prices", "description": "Get current gas/fee estimates for a blockchain", "operationId": "blockchain_POST_gas", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "chain": "ethereum", "gasPrice": 25.5, "unit": "gwei", "estimates": { "slow": 20.4, "standard": 25.5, "fast": 30.6 }, "baseFee": 22.3 } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Blockchain network", "example": "ethereum" } }, "required": [ "chain" ] }, "example": { "chain": "ethereum" } } } } } }, "/api/v1/blockchain-tools/watch": { "post": { "tags": [ "Blockchain Tools" ], "summary": "Watch Wallet", "description": "Register wallet for real-time webhook notifications\n\nPremium feature. Receive POST notifications to your webhook URL when transactions occur on monitored addresses.\n\nPremium tier required\n\nContact support to enable\n\nWebhook receives JSON payloads", "operationId": "blockchain_POST_watch", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address to monitor", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c" }, "chain": { "type": "string", "description": "Blockchain network", "example": "ethereum" }, "webhookUrl": { "type": "string", "description": "Your webhook endpoint URL", "example": "https://yoursite.com/webhook" } }, "required": [ "address", "chain", "webhookUrl" ] }, "example": { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f14c", "chain": "ethereum", "webhookUrl": "https://yoursite.com/webhook" } } } } } }, "/api/v1/compliance-tools/score-transaction": { "post": { "tags": [ "Blockchain Compliance" ], "summary": "Score Transaction", "description": "Get AML/CFT risk score for a blockchain transaction by hash\n\nAnalyses 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.\n\nScore range: 1 (critical risk) to 100 (no risk)\n\nSeverity levels: CRITICAL_RISK, HIGH_RISK, MEDIUM_RISK, LOW_RISK, NO_RISK", "operationId": "compliance_POST_score_transaction", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hash": { "type": "string", "description": "The transaction hash to analyse", "example": "0x6af2077627203fa96939c7866e59835b3c0ff97ec73da95d2c8cc37291335650" }, "chain": { "type": "string", "description": "Blockchain network (bitcoin, ethereum, polygon, bsc, tron, solana, litecoin, dogecoin, ripple, avalanche, arbitrum, optimism, base, stellar, tezos, ton)", "example": "ethereum" }, "analysis_type": { "type": "string", "description": "Analysis depth: ASSIGNED (entity-only), INCOMING (source of funds), OUTGOING (destination), FULL (complete)", "example": "INCOMING" }, "coin": { "type": "string", "description": "Specific coin/token to analyse (default ALL)", "example": "ALL" }, "depth": { "type": "integer", "description": "Max hop depth for tracing (UTXO: up to 100, account-based: up to 6)", "example": "3" } }, "required": [ "hash", "chain" ] }, "example": { "hash": "0x6af2077627203fa96939c7866e59835b3c0ff97ec73da95d2c8cc37291335650", "chain": "ethereum", "analysis_type": "INCOMING" } } } } } }, "/api/v1/compliance-tools/score-address": { "post": { "tags": [ "Blockchain Compliance" ], "summary": "Score Address", "description": "Get AML/CFT risk score for a blockchain address\n\nAnalyses 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.\n\nBest for KYC/KYW (Know Your Wallet) checks\n\nFULL analysis covers both fund sources and destinations", "operationId": "compliance_POST_score_address", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The blockchain address to analyse", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "chain": { "type": "string", "description": "Blockchain network", "example": "ethereum" }, "analysis_type": { "type": "string", "description": "Analysis depth (default FULL)", "example": "FULL" }, "coin": { "type": "string", "description": "Specific coin/token (default ALL)", "example": "ALL" }, "depth": { "type": "integer", "description": "Max hop depth for tracing", "example": "3" } }, "required": [ "address", "chain" ] }, "example": { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "chain": "ethereum", "analysis_type": "FULL" } } } } } }, "/api/v1/compliance-tools/score-wallet": { "post": { "tags": [ "Blockchain Compliance" ], "summary": "Score Wallet Cluster", "description": "Get AML/CFT risk score for a wallet cluster by reference address\n\nAnalyses 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.\n\nWallet clustering groups addresses owned by the same entity\n\nTop 10 counterparties returned per direction", "operationId": "compliance_POST_score_wallet", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Reference address of the wallet cluster", "example": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" }, "chain": { "type": "string", "description": "Blockchain network", "example": "bitcoin" }, "analysis_type": { "type": "string", "description": "Analysis depth (default FULL)", "example": "FULL" }, "coin": { "type": "string", "description": "Specific coin/token (default ALL)", "example": "MAIN" }, "depth": { "type": "integer", "description": "Max hop depth for tracing", "example": "5" } }, "required": [ "address", "chain" ] }, "example": { "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "chain": "bitcoin", "analysis_type": "FULL" } } } } } }, "/api/v1/compliance-tools/supported-chains": { "get": { "tags": [ "Blockchain Compliance" ], "summary": "List Supported Chains", "description": "List all blockchains supported for compliance scoring", "operationId": "compliance_GET_supported_chains", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "supported_chains": [ "bitcoin", "ethereum", "polygon", "bsc", "tron", "solana", "litecoin", "dogecoin", "ripple", "avalanche", "arbitrum", "optimism", "base", "stellar", "tezos", "ton" ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/email/send": { "post": { "tags": [ "Email API" ], "summary": "Send Email", "description": "Send transactional emails via your verified domain", "operationId": "email_POST_send", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "id": "550e8400-e29b-41d4-a716-446655440000", "resend_id": "re_abc123xyz" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "Sender email (must be from verified domain)", "example": "notifications@yourdomain.com" }, "to": { "type": "string | string[]", "description": "Recipient email(s)", "example": "customer@example.com" }, "subject": { "type": "string", "description": "Email subject line", "example": "Order Confirmation" }, "html": { "type": "string", "description": "HTML body content", "example": "

Thank you!

" }, "text": { "type": "string", "description": "Plain text body", "example": "Thank you for your order." }, "cc": { "type": "string | string[]", "description": "CC recipient(s)", "example": "copy@example.com" }, "bcc": { "type": "string | string[]", "description": "BCC recipient(s)", "example": "archive@example.com" }, "reply_to": { "type": "string", "description": "Reply-to address", "example": "support@yourdomain.com" } }, "required": [ "from", "to", "subject" ] }, "example": { "from": "notifications@yourdomain.com", "to": "customer@example.com", "subject": "Order Confirmation", "html": "

Thank you for your order!

Order #12345 confirmed.

" } } } } } }, "/api/v1/email/domains": { "post": { "tags": [ "Email API" ], "summary": "Add Domain", "description": "Register a custom sending domain", "operationId": "email_POST_domains", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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 } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain to add", "example": "mail.yourdomain.com" } }, "required": [ "domain" ] }, "example": { "domain": "mail.yourdomain.com" } } } } }, "get": { "tags": [ "Email API" ], "summary": "List Domains", "description": "List all registered email domains with status", "operationId": "email_GET_domains", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/email/domains/verify": { "post": { "tags": [ "Email API" ], "summary": "Verify Domain", "description": "Trigger DNS verification check", "operationId": "email_POST_domains_verify", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "status": "verified", "verified_at": "2024-01-15T02:30:00Z" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "string", "description": "Domain ID to verify", "example": "dom_abc123" } }, "required": [ "domain_id" ] }, "example": { "domain_id": "dom_abc123" } } } } } }, "/api/v1/email/domains/:domain_id": { "delete": { "tags": [ "Email API" ], "summary": "Delete Domain", "description": "Remove a domain from your account", "operationId": "email_DELETE_domains_domain_id", "parameters": [ { "name": "domain_id", "in": "query", "required": true, "description": "Domain ID (URL param)", "schema": { "type": "string" }, "example": "dom_abc123" } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Domain removed successfully" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/swifthub/swift-validate": { "post": { "tags": [ "SwiftHub" ], "summary": "Validate Payment", "description": "Validate SWIFT payment before submission", "operationId": "swifthub_POST_swift_validate", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "valid": true, "errors": [], "warnings": [ { "code": "W001", "field": "purpose_code", "message": "Purpose code recommended for EUR payments" } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditor_name": { "type": "string", "description": "Beneficiary name", "example": "ACME Corporation" }, "creditor_iban": { "type": "string", "description": "Beneficiary IBAN", "example": "DE89370400440532013000" }, "creditor_bic": { "type": "string", "description": "Beneficiary BIC/SWIFT", "example": "COBADEFFXXX" }, "amount": { "type": "number", "description": "Payment amount", "example": "10000.00" }, "currency": { "type": "string", "description": "ISO currency code", "example": "EUR" }, "remittance_unstructured": { "type": "string", "description": "Payment reference", "example": "Invoice INV-2024-001" }, "charge_type": { "type": "string", "description": "SHA, OUR, or BEN", "example": "SHA" }, "purpose_code": { "type": "string", "description": "ISO purpose code", "example": "SALA" } }, "required": [ "creditor_name", "creditor_iban", "amount", "currency" ] }, "example": { "creditor_name": "ACME Corporation", "creditor_iban": "DE89370400440532013000", "creditor_bic": "COBADEFFXXX", "amount": 10000, "currency": "EUR", "remittance_unstructured": "Invoice INV-2024-001" } } } } } }, "/api/v1/swifthub/swift-payments": { "post": { "tags": [ "SwiftHub" ], "summary": "Create Payment", "description": "Create and submit a new SWIFT payment", "operationId": "swifthub_POST_swift_payments", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "payment_id": "pmt_abc123xyz", "uetr": "550e8400-e29b-41d4-a716-446655440000", "status": "validated", "created_at": "2024-01-15T10:30:00Z" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditor_name": { "type": "string", "description": "Beneficiary name", "example": "ACME Corporation" }, "creditor_iban": { "type": "string", "description": "Beneficiary IBAN", "example": "DE89370400440532013000" }, "creditor_bic": { "type": "string", "description": "Beneficiary BIC", "example": "COBADEFFXXX" }, "amount": { "type": "number", "description": "Payment amount", "example": "10000.00" }, "currency": { "type": "string", "description": "ISO currency code", "example": "EUR" }, "charge_type": { "type": "string", "description": "SHA, OUR, or BEN", "example": "SHA" }, "purpose_code": { "type": "string", "description": "ISO purpose code", "example": "SALA" }, "remittance_unstructured": { "type": "string", "description": "Payment reference (max 140 chars)", "example": "Invoice INV-2024-001" }, "requested_execution_date": { "type": "string", "description": "ISO date for execution", "example": "2024-12-15" } }, "required": [ "creditor_name", "creditor_iban", "amount", "currency" ] }, "example": { "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" } } } } } }, "/api/v1/swifthub/swift-payments/:id": { "get": { "tags": [ "SwiftHub" ], "summary": "Get Payment Details", "description": "Retrieve payment status and history", "operationId": "swifthub_GET_swift_payments_id", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Payment ID (URL param)", "schema": { "type": "string" }, "example": "pmt_abc123xyz" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } ] } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/swifthub/swift-cancel": { "post": { "tags": [ "SwiftHub" ], "summary": "Cancel Payment", "description": "Request cancellation of a pending payment\n\nNot all payments can be cancelled\n\nSuccess depends on payment status", "operationId": "swifthub_POST_swift_cancel", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "payment_id": "pmt_abc123xyz", "status": "cancellation_requested", "message": "Cancellation request submitted" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "Payment ID to cancel", "example": "pmt_abc123xyz" }, "reason": { "type": "string", "description": "Cancellation reason", "example": "Duplicate payment" } }, "required": [ "payment_id", "reason" ] }, "example": { "payment_id": "pmt_abc123xyz", "reason": "Duplicate payment" } } } } } }, "/api/v1/swifthub/swift-repair": { "post": { "tags": [ "SwiftHub" ], "summary": "Repair Payment", "description": "Correct and resubmit a rejected payment", "operationId": "swifthub_POST_swift_repair", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "payment_id": "pmt_abc123xyz", "status": "validated", "message": "Payment repaired and revalidated" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "Payment ID to repair", "example": "pmt_abc123xyz" }, "corrections": { "type": "object", "description": "Fields to correct", "example": "{ \"creditor_name\": \"ACME Corp Ltd\" }" }, "reason": { "type": "string", "description": "Repair reason", "example": "Corrected beneficiary name" } }, "required": [ "payment_id", "corrections" ] }, "example": { "payment_id": "pmt_abc123xyz", "corrections": { "creditor_name": "ACME Corp Ltd" }, "reason": "Corrected beneficiary name" } } } } } }, "/api/v1/vat-validation/": { "post": { "tags": [ "VAT Validation" ], "summary": "Validate VAT Number", "description": "Validate EU VAT numbers and retrieve company information\n\nValidates VAT number format and checks against EU VIES database. Returns company registration details.", "operationId": "vat_POST", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vat_number": { "type": "string", "description": "VAT number with country prefix", "example": "DE123456789" }, "country_code": { "type": "string", "description": "ISO 2-letter country code (optional if in VAT number)", "example": "DE" } }, "required": [ "vat_number" ] }, "example": { "vat_number": "DE123456789" } } } } } }, "/api/v1/kyb-tools/lei/{lei}": { "get": { "tags": [ "KYB / Business Registry" ], "summary": "Lookup LEI Record", "description": "Fetch the full Legal Entity Identifier record from GLEIF", "operationId": "kyb_GET_lei_lei", "parameters": [ { "name": "lei", "in": "query", "required": true, "description": "20-character LEI code", "schema": { "type": "string" }, "example": "529900T8BM49AURSDO55" } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "found": true, "lei": "529900T8BM49AURSDO55", "legal_name": "GLEIF", "jurisdiction": "CH", "provider": "gleif" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/kyb-tools/search": { "get": { "tags": [ "KYB / Business Registry" ], "summary": "Search Legal Entities", "description": "Search GLEIF by legal name, optionally filtered by country", "operationId": "kyb_GET_search", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search term (legal name)", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO-3166-1 alpha-2 country code", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (1-50, default 10)", "schema": { "type": "number" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "query": "Acme", "total": 12, "results": [], "provider": "gleif" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/kyb-tools/fuzzy": { "get": { "tags": [ "KYB / Business Registry" ], "summary": "Fuzzy Name Suggestions", "description": "Autocomplete legal entity names with fuzzy matching", "operationId": "kyb_GET_fuzzy", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Partial name", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "query": "Acm", "suggestions": [], "provider": "gleif" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/sanctions-tools/screen": { "post": { "tags": [ "Sanctions & PEP Screening" ], "summary": "Screen Name (All Lists)", "description": "Screen a person or company against the consolidated OpenSanctions dataset (OFAC, EU, UN, UK, PEPs and more).", "operationId": "sanctions_POST_screen", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "name": "Vladimir Putin", "match_count": 1, "is_match": true, "best_score": 1, "results": [], "provider": "opensanctions" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name to screen" }, "schema": { "type": "string", "description": "\"Person\" (default) or \"Company\"" }, "country": { "type": "string", "description": "ISO country hint to refine match" }, "birth_date": { "type": "string", "description": "YYYY-MM-DD for persons" }, "threshold": { "type": "number", "description": "Match score threshold (0-1, default 0.7)" }, "limit": { "type": "number", "description": "Max results returned (default 5)" } }, "required": [ "name" ] }, "example": { "name": "Vladimir Putin", "schema": "Person", "threshold": 0.7 } } } } } }, "/api/v1/sanctions-tools/ofac-screen": { "post": { "tags": [ "Sanctions & PEP Screening" ], "summary": "Screen Against OFAC SDN", "description": "Restrict screening to the US OFAC SDN list specifically.", "operationId": "sanctions_POST_ofac_screen", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "name": "John Doe", "list": "OFAC SDN", "match_count": 0, "is_match": false, "results": [], "provider": "opensanctions" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name" }, "schema": { "type": "string", "description": "\"Person\" or \"Company\"" }, "threshold": { "type": "number", "description": "0-1, default 0.7" } }, "required": [ "name" ] }, "example": { "name": "John Doe" } } } } } }, "/api/v1/sanctions-tools/search": { "get": { "tags": [ "Sanctions & PEP Screening" ], "summary": "Free-text Search", "description": "Search across sanction datasets", "operationId": "sanctions_GET_search", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string" } }, { "name": "dataset", "in": "query", "required": false, "description": "Dataset (default \"default\")", "schema": { "type": "string" } }, { "name": "schema", "in": "query", "required": false, "description": "Entity schema", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "query": "Acme", "total": 0, "results": [], "provider": "opensanctions" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/sanctions-tools/entity/{id}": { "get": { "tags": [ "Sanctions & PEP Screening" ], "summary": "Get Entity Detail", "description": "Fetch the full record for a sanctioned entity by id. Requires an OpenSanctions data subscription on the account; contact support@utilitypro.eu to enable.", "operationId": "sanctions_GET_entity_id", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Entity id returned by /screen or /search", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "id": "NK-...", "caption": "...", "provider": "opensanctions" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/calendar-tools/holidays/{country}/{year}": { "get": { "tags": [ "Banking Calendar" ], "summary": "List Public Holidays", "description": "Returns all public holidays for a country and year", "operationId": "calendar_GET_holidays_country_year", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO-3166-1 alpha-2", "schema": { "type": "string" }, "example": "DE" }, { "name": "year", "in": "query", "required": true, "description": "YYYY", "schema": { "type": "string" }, "example": "2026" } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "country": "DE", "year": 2026, "count": 12, "holidays": [], "provider": "nager.date" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/calendar-tools/is-holiday": { "get": { "tags": [ "Banking Calendar" ], "summary": "Is Business Day", "description": "Returns whether a given date is a business day, weekend or holiday", "operationId": "calendar_GET_is_holiday", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO country", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "YYYY-MM-DD (default today)", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "country": "DE", "date": "2026-12-25", "is_business_day": false, "is_public_holiday": true, "holiday": { "name": "Christmas Day" }, "provider": "nager.date" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/calendar-tools/next-business-day": { "get": { "tags": [ "Banking Calendar" ], "summary": "Add Business Days", "description": "Skip weekends and holidays to compute settlement dates", "operationId": "calendar_GET_next_business_day", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO country", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "Start date (default today)", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Business days to add (1-60, default 1)", "schema": { "type": "number" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/calendar-tools/supported-countries": { "get": { "tags": [ "Banking Calendar" ], "summary": "Supported Countries", "description": "List ISO codes covered by the holidays dataset", "operationId": "calendar_GET_supported_countries", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "countries": [ { "countryCode": "DE", "name": "Germany" } ], "provider": "nager.date" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/reference-tools/countries": { "get": { "tags": [ "Reference Data" ], "summary": "List All Countries", "description": "All ISO countries with currencies, languages, calling codes, and region metadata", "operationId": "reference_GET_countries", "parameters": [], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "count": 250, "countries": [], "provider": "mledoze/countries" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/reference-tools/country/{code}": { "get": { "tags": [ "Reference Data" ], "summary": "Country Detail", "description": "Look up a country by ISO 2- or 3-letter code", "operationId": "reference_GET_country_code", "parameters": [ { "name": "code", "in": "query", "required": true, "description": "ISO code", "schema": { "type": "string" }, "example": "DE" } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "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" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/reference-tools/vat-rates/{country}": { "get": { "tags": [ "Reference Data" ], "summary": "VAT Rate Lookup", "description": "Standard and reduced VAT rates per country (curated EU table)", "operationId": "reference_GET_vat_rates_country", "parameters": [ { "name": "country", "in": "query", "required": false, "description": "ISO 2-letter; omit for full table", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "country": "DE", "country_name": "Germany", "standard_rate": 19, "reduced_rates": [ 7 ], "super_reduced_rate": null, "parking_rate": null, "provider": "utilitypro" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/reference-tools/fx-rates": { "get": { "tags": [ "Reference Data" ], "summary": "Daily FX Rates", "description": "Foreign exchange rates relative to a base currency", "operationId": "reference_GET_fx_rates", "parameters": [ { "name": "base", "in": "query", "required": false, "description": "Base currency (default EUR)", "schema": { "type": "string" } }, { "name": "symbols", "in": "query", "required": false, "description": "Comma-separated target currencies", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "YYYY-MM-DD for historical rates", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "base": "EUR", "date": "2026-05-04", "rates": { "USD": 1.08, "GBP": 0.86 }, "provider": "vatcomply" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/reference-tools/vat-validate": { "get": { "tags": [ "Reference Data" ], "summary": "EU VAT Validate", "description": "Validate an EU VAT number via VATComply", "operationId": "reference_GET_vat_validate", "parameters": [ { "name": "vat", "in": "query", "required": true, "description": "VAT number with country prefix", "schema": { "type": "string" }, "example": "DE123456789" } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "country_code": "DE", "vat_number": "123456789", "valid": true, "name": "Acme GmbH", "provider": "vatcomply" } } } }, "401": { "description": "Missing or invalid credentials" }, "429": { "description": "Rate limit exceeded" } } } } } }