{"openapi":"3.1.0","info":{"title":"Veille API Reference","description":"Complete API reference documentation.","version":"1.0.0"},"servers":[{"url":"https://api.veille.io","description":"API Server"}],"paths":{"/v1/stats":{"get":{"summary":"Stats","description":"Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.","operationId":"stats","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"engine","in":"query","required":false,"description":"API family to check, for example `vat`. Provide at least `engine` or `path`.","schema":{"type":"string","description":"API family to check, for example `vat`. Provide at least `engine` or `path`."}},{"name":"path","in":"query","required":false,"description":"Specific endpoint to check, for example `/v1/vat`. If you also pass `engine`, use an endpoint from that API.","schema":{"type":"string","description":"Specific endpoint to check, for example `/v1/vat`. If you also pass `engine`, use an endpoint from that API."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"nullable":true},"engine":{"type":"string"},"health":{"type":"string"},"window":{"type":"string"},"success_rate":{"type":"number"},"avg_response_time_ms":{"type":"integer"}}},"examples":{"Engine health snapshot":{"value":{"path":null,"engine":"vat","health":"operational","window":"1h","success_rate":99.412,"avg_response_time_ms":840}},"Path health snapshot":{"value":{"path":"/v1/vat","engine":"vat","health":"operational","window":"1h","success_rate":99.412,"avg_response_time_ms":840}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/usage":{"get":{"summary":"Usage","description":"Retrieve real-time usage statistics and credit balance for your Veille account.","operationId":"usage","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"packs":{"nullable":true},"period":{"type":"object","properties":{"end":{"type":"string"},"start":{"type":"string"}}},"account":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"api_key":{"type":"object","properties":{"alias":{"type":"string"},"active":{"type":"boolean"},"quotas":{"type":"object","properties":{"daily":{"nullable":true},"total":{"nullable":true},"weekly":{"nullable":true},"monthly":{"nullable":true}}},"expires":{"nullable":true},"category":{"type":"string"}}},"credits":{"type":"object","properties":{"given":{"type":"integer"},"consumed":{"type":"integer"},"remaining":{"type":"integer"},"percent_used":{"type":"integer"}}},"remaining":{"type":"integer"},"rate_limit":{"type":"object","properties":{"per_minute":{"nullable":true},"per_second":{"nullable":true}}},"total_used":{"type":"integer"},"renewal_date":{"type":"string"},"subscription":{"type":"object","properties":{"used":{"type":"integer"},"total":{"type":"integer"},"remaining":{"type":"integer"},"percent_used":{"type":"integer"}}}}},"examples":{"Account usage overview":{"value":{"packs":null,"period":{"end":"2026-04-25","start":"2026-03-25"},"account":{"name":"Microsoft","slug":"microsoft"},"api_key":{"alias":"my-api-key","active":true,"quotas":{"daily":null,"total":null,"weekly":null,"monthly":null},"expires":null,"category":"development"},"credits":{"given":0,"consumed":0,"remaining":0,"percent_used":0},"remaining":0,"rate_limit":{"per_minute":null,"per_second":null},"total_used":15871,"renewal_date":"2026-04-25","subscription":{"used":15871,"total":50,"remaining":0,"percent_used":31742}}},"Account with one-time packs":{"value":{"packs":{"used":15200000,"count":2,"items":[{"id":"cmhtn…","used":12500000,"title":"Ultimate","total":12500000,"exhausted":true,"remaining":0,"percent_used":100,"purchased_at":"2025-11-10"},{"id":"cmlc9…","used":2700000,"title":"Ultimate","total":12500000,"exhausted":false,"remaining":9800000,"percent_used":21.6,"purchased_at":"2026-02-07"}],"total":25000000,"current":{"id":"cmlc9…","used":2700000,"title":"Ultimate","total":12500000,"exhausted":false,"remaining":9800000,"percent_used":21.6,"purchased_at":"2026-02-07"},"remaining":9800000,"percent_used":60.8,"all_exhausted":false,"current_index":2,"exhausted_count":1},"period":{"end":"2026-10-01","start":"2026-09-01"},"account":{"name":"Microsoft","slug":"microsoft"},"api_key":{"alias":"my-api-key","active":true,"quotas":{"daily":null,"total":null,"weekly":null,"monthly":null},"expires":null,"category":"development"},"credits":{"given":0,"consumed":0,"remaining":0,"percent_used":0},"remaining":9800000,"rate_limit":{"per_minute":null,"per_second":null},"total_used":15200000,"renewal_date":"2026-10-01","subscription":{"used":15200000,"total":25000000,"remaining":9800000,"percent_used":60.8}}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/intelligence/email":{"get":{"summary":"Email Validation","description":"Validate any email address in a single call. Detects disposable and temporary inboxes, identifies role accounts, public webmail, relay services, and returns a 0-100 risk score. For deep deliverability verification (SMTP check, catch-all detection), use the Email Qualification endpoint.\n\n**Credit cost:** 3 credits per call","operationId":"intelligence-email","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"The email address to validate (e.g. `john@example.com`). Automatically normalized to lowercase.","schema":{"type":"string","description":"The email address to validate (e.g. `john@example.com`). Automatically normalized to lowercase."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"dns":{"type":"object","properties":{"mx":{"type":"boolean"},"spf":{"type":"string"},"dmarc":{"nullable":true},"spf_valid":{"type":"boolean"},"mx_records":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string"},"priority":{"type":"integer"}}}},"dmarc_valid":{"type":"boolean"},"mx_providers":{"type":"array","items":{}}}},"email":{"type":"string"},"domain":{"type":"string"},"is_alias":{"type":"boolean"},"education":{"type":"boolean"},"role_type":{"nullable":true},"disposable":{"type":"boolean"},"risk_score":{"type":"integer"},"did_you_mean":{"nullable":true},"has_gravatar":{"type":"boolean"},"relay_domain":{"type":"boolean"},"role_account":{"type":"boolean"},"public_domain":{"type":"boolean"},"normalized_email":{"type":"string"}}},"examples":{"Disposable email":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:_spf.tempmail.org ~all","dmarc":null,"spf_valid":true,"mx_records":[{"hostname":"mx1.tempmail.org","priority":10}],"dmarc_valid":false,"mx_providers":[]},"email":"user@tempmail.org","domain":"tempmail.org","is_alias":false,"education":false,"role_type":null,"disposable":true,"risk_score":72,"did_you_mean":null,"has_gravatar":false,"relay_domain":false,"role_account":false,"public_domain":false,"normalized_email":"user@tempmail.org"}},"Legitimate corporate email":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:spf.protection.outlook.com -all","dmarc":"v=DMARC1; p=reject; rua=mailto:dmarc@airbus.com","spf_valid":true,"mx_records":[{"hostname":"airbus-com.mail.protection.outlook.com","priority":10}],"dmarc_valid":true,"mx_providers":[{"slug":"microsoft","type":"mailbox","grade":"professional"}]},"email":"contact@airbus.com","domain":"airbus.com","is_alias":false,"education":false,"role_type":"contact","disposable":false,"risk_score":10,"did_you_mean":null,"has_gravatar":false,"relay_domain":false,"role_account":true,"public_domain":false,"normalized_email":"contact@airbus.com"}},"Public webmail (Gmail)":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:_spf.google.com ~all","dmarc":"v=DMARC1; p=none; rua=mailto:mailauth-reports@google.com","spf_valid":true,"mx_records":[{"hostname":"gmail-smtp-in.l.google.com","priority":5},{"hostname":"alt1.gmail-smtp-in.l.google.com","priority":10}],"dmarc_valid":true,"mx_providers":[{"slug":"google","type":"mailbox","grade":"professional"}]},"email":"alice@gmail.com","domain":"gmail.com","is_alias":false,"education":false,"role_type":null,"disposable":false,"risk_score":0,"did_you_mean":null,"has_gravatar":true,"relay_domain":false,"role_account":false,"public_domain":true,"normalized_email":"alice@gmail.com"}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/intelligence/emailq":{"get":{"summary":"Email Qualification","description":"Deep email deliverability verification. Performs full Email Validation plus SMTP inbox check, catch-all detection, and returns a qualification verdict (valid, invalid, risky, disposable, unknown).\n\n**Credit cost:** 5 credits per call","operationId":"intelligence-emailq","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"The email address to qualify (e.g. `john@example.com`). Automatically normalized to lowercase.","schema":{"type":"string","description":"The email address to qualify (e.g. `john@example.com`). Automatically normalized to lowercase."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"dns":{"type":"object","properties":{"mx":{"type":"boolean"},"spf":{"type":"string"},"dmarc":{"type":"string"},"spf_valid":{"type":"boolean"},"mx_records":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string"},"priority":{"type":"integer"}}}},"dmarc_valid":{"type":"boolean"},"mx_providers":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"type":{"type":"string"},"grade":{"type":"string"}}}}}},"email":{"type":"string"},"domain":{"type":"string"},"is_alias":{"type":"boolean"},"education":{"type":"boolean"},"role_type":{"type":"string"},"disposable":{"type":"boolean"},"risk_score":{"type":"integer"},"smtp_valid":{"type":"boolean"},"did_you_mean":{"nullable":true},"has_gravatar":{"type":"boolean"},"relay_domain":{"type":"boolean"},"role_account":{"type":"boolean"},"public_domain":{"type":"boolean"},"qualification":{"type":"string"},"normalized_email":{"type":"string"}}},"examples":{"Valid corporate inbox":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:spf.protection.outlook.com -all","dmarc":"v=DMARC1; p=reject; rua=mailto:dmarc@airbus.com","spf_valid":true,"mx_records":[{"hostname":"airbus-com.mail.protection.outlook.com","priority":10}],"dmarc_valid":true,"mx_providers":[{"slug":"microsoft","type":"mailbox","grade":"professional"}]},"email":"contact@airbus.com","domain":"airbus.com","is_alias":false,"education":false,"role_type":"contact","disposable":false,"risk_score":10,"smtp_valid":true,"did_you_mean":null,"has_gravatar":false,"relay_domain":false,"role_account":true,"public_domain":false,"qualification":"valid","normalized_email":"contact@airbus.com"}},"Invalid inbox (does not exist)":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:spf.protection.outlook.com -all","dmarc":"v=DMARC1; p=reject; rua=mailto:dmarc@airbus.com","spf_valid":true,"mx_records":[{"hostname":"airbus-com.mail.protection.outlook.com","priority":10}],"dmarc_valid":true,"mx_providers":[{"slug":"microsoft","type":"mailbox","grade":"professional"}]},"email":"nonexistent.user.xyz@airbus.com","domain":"airbus.com","is_alias":false,"education":false,"role_type":null,"disposable":false,"risk_score":80,"smtp_valid":false,"did_you_mean":null,"has_gravatar":false,"relay_domain":false,"role_account":false,"public_domain":false,"qualification":"invalid","normalized_email":"nonexistent.user.xyz@airbus.com"}},"Disposable email (skips SMTP)":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:_spf.tempmail.org ~all","dmarc":null,"spf_valid":true,"mx_records":[{"hostname":"mx1.tempmail.org","priority":10}],"dmarc_valid":false,"mx_providers":[]},"email":"user@tempmail.org","domain":"tempmail.org","is_alias":false,"education":false,"role_type":null,"disposable":true,"risk_score":85,"smtp_valid":null,"did_you_mean":null,"has_gravatar":false,"relay_domain":false,"role_account":false,"public_domain":false,"qualification":"disposable","normalized_email":"user@tempmail.org"}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/intelligence/phone":{"get":{"summary":"Phone Validation","description":"Validate any phone number in E.164 format. Detects disposable and virtual numbers, identifies carrier and line type (mobile/fixed/VoIP), returns country and timezone, and computes a 0-100 risk score.\n\n**Status:** Experimental\n\n**Credit cost:** 1 credit per call","operationId":"intelligence-phone","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"The phone number to validate in E.164 format (must start with `+`, e.g. `+33612345678`).","schema":{"type":"string","description":"The phone number to validate in E.164 format (must start with `+`, e.g. `+33612345678`)."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"carrier":{"type":"string"},"country":{"type":"string"},"is_spam":{"type":"boolean"},"is_valid":{"type":"boolean"},"location":{"type":"string"},"is_threat":{"type":"boolean"},"line_type":{"type":"string"},"timezones":{"type":"array","items":{"type":"string"}},"is_virtual":{"type":"boolean"},"risk_score":{"type":"integer"},"e164_format":{"type":"string"},"number_type":{"type":"string"},"carrier_type":{"type":"string"},"country_code":{"type":"string"},"country_name":{"type":"string"},"source_count":{"type":"integer"},"is_disposable":{"type":"boolean"},"national_format":{"type":"string"},"international_format":{"type":"string"}}},"examples":{"Valid French mobile (Orange)":{"value":{"carrier":"Orange","country":"FR","is_spam":false,"is_valid":true,"location":"France","is_threat":false,"line_type":"mobile","timezones":["Europe/Paris"],"is_virtual":false,"risk_score":0,"e164_format":"+33612345678","number_type":"mobile","carrier_type":"mno","country_code":"33","country_name":"France","source_count":0,"is_disposable":false,"national_format":"06 12 34 56 78","international_format":"+33 6 12 34 56 78"}},"VoIP number (Twilio)":{"value":{"carrier":"Twilio","country":"US","is_spam":false,"is_valid":true,"location":"California","is_threat":false,"line_type":"voip","timezones":["America/Los_Angeles"],"is_virtual":true,"risk_score":20,"e164_format":"+14155552671","number_type":"voip","carrier_type":"voip","country_code":"1","country_name":"United States","source_count":0,"is_disposable":false,"national_format":"(415) 555-2671","international_format":"+1 415-555-2671"}},"Disposable number (found on SMS receiving site)":{"value":{"carrier":"Lycamobile","country":"GB","is_spam":false,"is_valid":true,"location":"United Kingdom","is_threat":false,"line_type":"mobile","timezones":["Europe/London"],"is_virtual":false,"risk_score":60,"e164_format":"+447538299689","number_type":"mobile","carrier_type":"mvno","country_code":"44","country_name":"United Kingdom","source_count":3,"is_disposable":true,"national_format":"07538 299689","international_format":"+44 7538 299689"}},"Missing + prefix":{"value":{"error":"Phone number must be in E.164 format (starting with '+').","status":400}},"Invalid phone number":{"value":{"error":"Invalid phone number format.","status":400}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/intelligence/ip":{"get":{"summary":"IP Reputation","description":"Assess the reputation of any IP address. Detects VPNs, proxies, Tor exit nodes, datacenter hosting, abusive traffic, and bots. Returns geolocation, network owner, and a 0-100 threat score.\n\n**Credit cost:** 2 credits per call","operationId":"intelligence-ip","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"The IP address to analyze (IPv4 or IPv6).","schema":{"type":"string","description":"The IP address to analyze (IPv4 or IPv6)."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string"},"asn":{"type":"object","properties":{"asn":{"type":"integer"},"org":{"type":"string"},"type":{"type":"string"},"descr":{"type":"string"},"active":{"type":"boolean"},"domain":{"type":"string"},"country":{"type":"string"}}},"is_tor":{"type":"boolean"},"is_vpn":{"type":"boolean"},"is_bogon":{"type":"boolean"},"is_proxy":{"type":"boolean"},"location":{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"latitude":{"type":"number"},"timezone":{"type":"string"},"longitude":{"type":"number"},"country_code":{"type":"string"}}},"is_abuser":{"type":"boolean"},"is_mobile":{"type":"boolean"},"is_crawler":{"type":"boolean"},"threat_score":{"type":"integer"},"is_datacenter":{"type":"boolean"}}},"examples":{"Clean residential IP":{"value":{"ip":"82.64.12.193","asn":{"asn":3215,"org":"France Telecom - Orange","type":"isp","descr":"Orange S.A.","active":true,"domain":"orange.com","country":"FR"},"is_tor":false,"is_vpn":false,"is_bogon":false,"is_proxy":false,"location":{"city":"Paris","state":"Ile-de-France","country":"France","latitude":48.8566,"timezone":"Europe/Paris","longitude":2.3522,"country_code":"FR"},"is_abuser":false,"is_mobile":false,"is_crawler":false,"threat_score":0,"is_datacenter":false}},"VPN / datacenter IP":{"value":{"ip":"104.238.140.68","asn":{"asn":20473,"org":"The Constant Company, LLC","type":"hosting","descr":"AS-CHOOPA","active":true,"domain":"vultr.com","country":"US"},"is_tor":false,"is_vpn":true,"is_bogon":false,"is_proxy":false,"location":{"city":"Piscataway","state":"New Jersey","country":"United States","latitude":40.4774,"timezone":"America/New_York","longitude":-74.2591,"country_code":"US"},"is_abuser":false,"is_mobile":false,"is_crawler":false,"threat_score":25,"is_datacenter":true}},"Tor exit node":{"value":{"ip":"185.220.101.34","asn":{"asn":205100,"org":"F3 Netze e.V.","type":"hosting","descr":"F3 Netze e.V.","active":true,"domain":"f3netze.de","country":"DE"},"is_tor":true,"is_vpn":false,"is_bogon":false,"is_proxy":false,"location":{"city":"Falkenstein","state":"Saxony","country":"Germany","latitude":50.4783,"timezone":"Europe/Berlin","longitude":12.3648,"country_code":"DE"},"is_abuser":true,"is_mobile":false,"is_crawler":false,"threat_score":70,"is_datacenter":true}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/vat/iban":{"get":{"summary":"IBAN Validation","description":"Validate any IBAN and retrieve associated bank details. Returns the BIC/SWIFT code, bank name, country, BBAN structural breakdown, and SEPA zone membership.\n\n**Credit cost:** 1 credit per call","operationId":"vat-iban","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"The IBAN to validate (e.g. FR7630006000011234567890189).","schema":{"type":"string","description":"The IBAN to validate (e.g. FR7630006000011234567890189)."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"bic":{"type":"string"},"bban":{"type":"string"},"iban":{"type":"string"},"valid":{"type":"boolean"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"branch_code":{"type":"string"},"country_code":{"type":"string"},"country_name":{"type":"string"},"in_sepa_zone":{"type":"boolean"},"account_number":{"type":"string"},"checksum_digits":{"type":"string"}}},"examples":{"Valid French IBAN":{"value":{"bic":"AGRIFRPPXXX","bban":"30006000011234567890189","iban":"FR7630006000011234567890189","valid":true,"bank_code":"30006","bank_name":"CREDIT AGRICOLE SA","branch_code":"00001","country_code":"FR","country_name":"France","in_sepa_zone":true,"account_number":"12345678901","checksum_digits":"76"}},"Valid German IBAN":{"value":{"bic":"COBADEFFXXX","bban":"370400440532013000","iban":"DE89370400440532013000","valid":true,"bank_code":"37040044","bank_name":"Commerzbank","branch_code":"","country_code":"DE","country_name":"Germany","in_sepa_zone":true,"account_number":"0532013000","checksum_digits":"89"}},"Invalid IBAN format":{"value":{"error":"Invalid IBAN format.","status":400}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/intelligence/domain":{"get":{"summary":"Domain Validation","description":"Check any domain instantly. Detects disposable email providers, public webmail, relay services, and education domains. Returns DNS health with MX provider detection, domain history, and optional SSL/TLS certificate transparency.\n\n**Credit cost:** 2 credits per call","operationId":"intelligence-domain","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"The domain to validate. Accepts raw domains (`tempmail.org`), full URLs (`https://www.tempmail.org/page`), or domains with `www.` prefix, all are normalized automatically.","schema":{"type":"string","description":"The domain to validate. Accepts raw domains (`tempmail.org`), full URLs (`https://www.tempmail.org/page`), or domains with `www.` prefix, all are normalized automatically."}},{"name":"certificate_transparency","in":"query","required":false,"description":"Enable Certificate Transparency lookup. Returns SSL/TLS certificate history, current certificate, issuers, and all Subject Alternative Names (SANs) ever associated with the domain. Adds 1-5 seconds of latency.","schema":{"type":"boolean","description":"Enable Certificate Transparency lookup. Returns SSL/TLS certificate history, current certificate, issuers, and all Subject Alternative Names (SANs) ever associated with the domain. Adds 1-5 seconds of latency.","default":false}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"dns":{"type":"object","properties":{"mx":{"type":"boolean"},"spf":{"type":"string"},"dmarc":{"nullable":true},"spf_valid":{"type":"boolean"},"mx_records":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string"},"priority":{"type":"integer"}}}},"dmarc_valid":{"type":"boolean"},"mx_providers":{"type":"array","items":{}}}},"tags":{"type":"array","items":{"type":"string"}},"whois":{"type":"object","properties":{"registrar":{"type":"string"},"updated_date":{"type":"string"},"creation_date":{"type":"string"},"expiration_date":{"type":"string"}}},"domain":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}},"education":{"type":"boolean"},"last_seen":{"type":"string"},"disposable":{"type":"boolean"},"first_seen":{"type":"string"},"is_subdomain":{"type":"boolean"},"relay_domain":{"type":"boolean"},"public_domain":{"type":"boolean"},"domain_age_days":{"type":"integer"}}},"examples":{"Disposable domain":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:_spf.tempmail.org ~all","dmarc":null,"spf_valid":true,"mx_records":[{"hostname":"mx1.tempmail.org","priority":10}],"dmarc_valid":false,"mx_providers":[]},"tags":["disposable"],"whois":{"registrar":"Namecheap, Inc.","updated_date":"2024-08-20","creation_date":"2023-09-15","expiration_date":"2025-09-15"},"domain":"tempmail.org","sources":["disposable-email-domains"],"education":false,"last_seen":"2026-02-18","disposable":true,"first_seen":"2024-03-12","is_subdomain":false,"relay_domain":false,"public_domain":false,"domain_age_days":892}},"Legitimate corporate domain":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:spf.protection.outlook.com -all","dmarc":"v=DMARC1; p=reject; rua=mailto:dmarc@airbus.com","spf_valid":true,"mx_records":[{"hostname":"airbus-com.mail.protection.outlook.com","priority":10}],"dmarc_valid":true,"mx_providers":[{"slug":"microsoft","type":"mailbox","grade":"professional"}]},"tags":[],"whois":{"registrar":"MarkMonitor Inc.","updated_date":"2024-05-10","creation_date":"1996-06-14","expiration_date":"2027-06-13"},"domain":"airbus.com","sources":[],"education":false,"last_seen":null,"disposable":false,"first_seen":null,"is_subdomain":false,"relay_domain":false,"public_domain":false,"domain_age_days":10482}},"Public webmail domain":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:_spf.google.com ~all","dmarc":"v=DMARC1; p=none; rua=mailto:mailauth-reports@google.com","spf_valid":true,"mx_records":[{"hostname":"gmail-smtp-in.l.google.com","priority":5},{"hostname":"alt1.gmail-smtp-in.l.google.com","priority":10}],"dmarc_valid":true,"mx_providers":[{"slug":"google","type":"mailbox","grade":"professional"}]},"tags":[],"whois":{"registrar":"MarkMonitor Inc.","updated_date":"2024-01-15","creation_date":"1995-08-13","expiration_date":"2026-08-12"},"domain":"gmail.com","sources":[],"education":false,"last_seen":null,"disposable":false,"first_seen":null,"is_subdomain":false,"relay_domain":false,"public_domain":true,"domain_age_days":9731}},"Relay / alias domain":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:simplelogin.co ~all","dmarc":"v=DMARC1; p=quarantine","spf_valid":true,"mx_records":[{"hostname":"mx1.simplelogin.co","priority":10},{"hostname":"mx2.simplelogin.co","priority":20}],"dmarc_valid":true,"mx_providers":[{"slug":"simplelogin","type":"forwarding","grade":"standard"}]},"tags":[],"whois":{"registrar":"Gandi SAS","updated_date":"2025-01-08","creation_date":"2019-06-10","expiration_date":"2026-06-10"},"domain":"simplelogin.io","sources":[],"education":false,"last_seen":null,"disposable":false,"first_seen":null,"is_subdomain":false,"relay_domain":true,"public_domain":false,"domain_age_days":2415}},"Education domain":{"value":{"dns":{"mx":true,"spf":"v=spf1 include:spf.protection.outlook.com -all","dmarc":"v=DMARC1; p=reject","spf_valid":true,"mx_records":[{"hostname":"mit-edu.mail.protection.outlook.com","priority":10}],"dmarc_valid":true,"mx_providers":[{"slug":"microsoft","type":"mailbox","grade":"professional"}]},"tags":["education"],"whois":{"registrar":null,"updated_date":"2023-07-19","creation_date":"1985-05-23","expiration_date":null},"domain":"mit.edu","sources":[],"education":true,"last_seen":null,"disposable":false,"first_seen":null,"is_subdomain":false,"relay_domain":false,"public_domain":false,"domain_age_days":14600}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/vat":{"get":{"summary":"VAT Validation","description":"Validate a European VAT number against the VIES database. Returns company name, registered address, and validity status for any EU member state.\n\n**Credit cost:** 1 credit per call","operationId":"vat","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"The VAT number to validate (e.g. FR40303265045).","schema":{"type":"string","description":"The VAT number to validate (e.g. FR40303265045)."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"vat_number":{"type":"string"},"company_name":{"type":"string"},"country_code":{"type":"string"},"company_address":{"type":"string"}}},"examples":{"Valid French VAT number":{"value":{"valid":true,"vat_number":"FR40303265045","company_name":"LVMH MOET HENNESSY LOUIS VUITTON","country_code":"FR","company_address":"22 AVE MONTAIGNE 75008 PARIS"}},"Valid German VAT number":{"value":{"valid":true,"vat_number":"DE302116501","company_name":"SAP SE","country_code":"DE","company_address":"DIETMAR-HOPP-ALLEE 16, 69190 WALLDORF"}},"Invalid VAT number":{"value":{"valid":false,"vat_number":"XX000000000","company_name":null,"country_code":"XX","company_address":null}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/vat/rates":{"get":{"summary":"Exchange Rates","description":"Get current ECB exchange rates for any supported base currency. Optionally filter to specific target currencies. Updated daily from the European Central Bank.\n\n**Credit cost:** 1 credit per call","operationId":"vat-rates","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"base","in":"query","required":false,"description":"Base currency ISO 4217 code (defaults to EUR).","schema":{"type":"string","default":"EUR","description":"Base currency ISO 4217 code (defaults to EUR)."}},{"name":"symbols","in":"query","required":false,"description":"Comma-separated target currency codes to filter (e.g. USD,GBP,JPY).","schema":{"type":"string","description":"Comma-separated target currency codes to filter (e.g. USD,GBP,JPY)."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"base":{"type":"string"},"date":{"type":"string"},"rates":{"type":"object","properties":{"AUD":{"type":"number"},"BRL":{"type":"number"},"CAD":{"type":"number"},"CHF":{"type":"number"},"CNY":{"type":"number"},"CZK":{"type":"number"},"DKK":{"type":"number"},"EUR":{"type":"integer"},"GBP":{"type":"number"},"HKD":{"type":"number"},"HUF":{"type":"number"},"IDR":{"type":"number"},"ILS":{"type":"number"},"INR":{"type":"number"},"ISK":{"type":"number"},"JPY":{"type":"number"},"KRW":{"type":"number"},"MXN":{"type":"number"},"MYR":{"type":"number"},"NOK":{"type":"number"},"NZD":{"type":"number"},"PHP":{"type":"number"},"PLN":{"type":"number"},"RON":{"type":"number"},"SEK":{"type":"number"},"SGD":{"type":"number"},"THB":{"type":"number"},"TRY":{"type":"number"},"USD":{"type":"number"},"ZAR":{"type":"number"}}}}},"examples":{"EUR base, all currencies":{"value":{"base":"EUR","date":"2026-02-20","rates":{"AUD":1.6697,"BRL":6.1358,"CAD":1.6112,"CHF":0.9132,"CNY":8.1294,"CZK":24.241,"DKK":7.4716,"EUR":1,"GBP":0.8728,"HKD":9.1961,"HUF":379.65,"IDR":19872.87,"ILS":3.6783,"INR":107.0155,"ISK":144.9,"JPY":182.63,"KRW":1705.81,"MXN":20.2402,"MYR":4.5927,"NOK":11.254,"NZD":1.9763,"PHP":68.428,"PLN":4.2238,"RON":5.0978,"SEK":10.6745,"SGD":1.4931,"THB":36.719,"TRY":51.5932,"USD":1.1767,"ZAR":18.9417}}},"EUR base, filtered to USD/GBP/JPY":{"value":{"base":"EUR","date":"2026-02-20","rates":{"GBP":0.8728,"JPY":182.63,"USD":1.1767}}},"USD base":{"value":{"base":"USD","date":"2026-02-20","rates":{"AUD":1.418968,"CAD":1.369253,"CHF":0.776069,"CNY":6.908643,"EUR":0.849834,"GBP":0.741735,"HKD":7.815161,"JPY":155.205235,"USD":1}}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/jobs/{id}":{"get":{"summary":"Jobs","description":"Poll the status, progress (0–100) and result of a job started with `is_async=true`. Polling is free. Poll until `status` is terminal: `CompletedJob`, `Error`, `NotFound` or `BadRequest`.","operationId":"jobs-id","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The `job_id` returned by an endpoint called with `is_async=true`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Job status, with the result once `status` is `CompletedJob`.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"success":{"type":["boolean","null"]},"status":{"type":"string","enum":["Queued","Running","CompletedJob","Error","NotFound","BadRequest"]},"endpoint":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"duration_ms":{"type":["number","null"]},"args":{"type":"object"},"result":{},"progress":{"type":["integer","null"]}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"404":{"description":"Not Found — no job with this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Job or content not found"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}}},"components":{"parameters":{"fields":{"name":"fields","in":"query","required":false,"description":"Comma-separated list of response fields to return, with dot notation for nested fields (e.g. `name,location.city`).","schema":{"type":"string"}},"is_async":{"name":"is_async","in":"query","required":false,"description":"Run the request as a background job: the API answers `202` with a `job_id` to poll on `GET /v1/jobs/{id}`.","schema":{"type":"boolean","default":false}},"soft_fail":{"name":"soft_fail","in":"query","required":false,"description":"Return HTTP 200 even when the request fails; the error is in the `error` field of the body.","schema":{"type":"boolean","default":false}}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. Include it in the x-api-key header for every request."}}}}