{"openapi":"3.1.0","info":{"title":"BizCheck API","version":"1.0.0","description":"BizCheck lets AI agents verify a company in one call: registry record, EU VAT validity, LEI and sanctions screening (EU, UN, OFAC, UK). Every fact carries its source and fetch time. Agents sign themselves up; 25 checks are free.\n\nFree: 25 checks per key. Pro: EUR 5/month, 2000 checks. A check is one call to /check, /company, /search or /sanctions."},"servers":[{"url":"https://bizcheck.app/api/v1"}],"security":[{"bearer":[]}],"paths":{"/signup":{"post":{"operationId":"signup","summary":"Create an API key (no human needed). The key is returned once. 5 per IP per 24h.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"}}}}}},"responses":{"200":{"description":"New key","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string"},"key_prefix":{"type":"string"},"label":{"type":"string"},"plan":{"enum":["free","pro"]},"checks_left":{"type":"integer"},"upgrade_url":{"type":"string","format":"uri"},"message":{"type":"string"}},"required":["api_key","key_prefix","plan","checks_left","upgrade_url"]}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account":{"get":{"operationId":"account","summary":"Plan, checks used and left, period end, upgrade_url.","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout":{"post":{"operationId":"getCheckoutLink","summary":"Checkout link tied to the calling key. Give it to a human; after payment the same key is Pro.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"const":"pro"}},"required":["plan"]}}}},"responses":{"200":{"description":"Checkout link","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"plan":{"enum":["pro"]},"price":{"type":"string"}},"required":["checkout_url","expires_at"]}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"operationId":"searchCompanies","summary":"Find companies by name. Costs 1 check.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":5,"minimum":1}}],"responses":{"200":{"description":"Matches","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"checks_left":{"type":["integer","null"]}}}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"out_of_checks: give error.upgrade_url to a human, then retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"out_of_checks","message":"This key has used its 25 free checks. Give the upgrade_url to your human. After they pay, retry with the same key.","upgrade_url":"https://checkout.example/c/9f2e..."}}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"source_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/{country}/{id}":{"get":{"operationId":"getCompany","summary":"One company by country and national registry code. Costs 1 check.","parameters":[{"name":"country","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company","content":{"application/json":{"schema":{"type":"object","required":["company","checks_left"],"properties":{"company":{"$ref":"#/components/schemas/Company"},"checks_left":{"type":"integer"}}},"example":{"company":{"id":"FI:0112038-9","country":"FI","registry_id":"0112038-9","name":"Nokia Oyj","former_names":["Oy Nokia Ab"],"status":"active","status_detail":"Registered in the Trade Register","legal_form":"Public limited company","incorporated_on":"1978-03-15","address":"Karakaari 7, 02610 ESPOO","vat_numbers":["FI01120389"],"industry":{"code":"70100","scheme":"TOL 2008","label":"Activities of head offices"},"website":"https://www.nokia.com","sources":[{"name":"Finnish Patent and Registration Office (PRH, YTJ open data)","url":"https://tietopalvelu.ytj.fi/yritys/0112038-9","fetched_at":"2026-11-04T09:12:40Z","licence":"CC BY 4.0, Finnish Patent and Registration Office"},{"name":"GLEIF (Global Legal Entity Identifier Foundation)","url":"https://search.gleif.org/#/record/549300A0JPRWG1KI7U06","fetched_at":"2026-11-04T09:12:40Z","licence":"CC0 1.0, GLEIF"}],"lei":"549300A0JPRWG1KI7U06"},"checks_left":23}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"out_of_checks: give error.upgrade_url to a human, then retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"out_of_checks","message":"This key has used its 25 free checks. Give the upgrade_url to your human. After they pay, retry with the same key.","upgrade_url":"https://checkout.example/c/9f2e..."}}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"source_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/check":{"post":{"operationId":"checkBusiness","summary":"Full check: registry, VAT, IBAN, sanctions, verdict with reasons. Costs 1 check. Send at least one field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"registry_id":{"type":"string"},"vat":{"type":"string"},"lei":{"type":"string"},"iban":{"type":"string"}},"minProperties":1},"example":{"name":"Nokia Oyj","country":"FI"}}}},"responses":{"200":{"description":"CheckReport","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckReport"},"example":{"query":{"name":"Nokia Oyj","country":"FI"},"verdict":"clear","reasons":["Nokia Oyj (FI 0112038-9) is active in Finnish Patent and Registration Office (PRH, YTJ open data).","No matches on the EU, OFAC, UK, UN sanctions lists."],"company":{"id":"FI:0112038-9","country":"FI","registry_id":"0112038-9","name":"Nokia Oyj","former_names":["Oy Nokia Ab"],"status":"active","status_detail":"Registered in the Trade Register","legal_form":"Public limited company","incorporated_on":"1978-03-15","address":"Karakaari 7, 02610 ESPOO","vat_numbers":["FI01120389"],"industry":{"code":"70100","scheme":"TOL 2008","label":"Activities of head offices"},"website":"https://www.nokia.com","sources":[{"name":"Finnish Patent and Registration Office (PRH, YTJ open data)","url":"https://tietopalvelu.ytj.fi/yritys/0112038-9","fetched_at":"2026-11-04T09:12:40Z","licence":"CC BY 4.0, Finnish Patent and Registration Office"},{"name":"GLEIF (Global Legal Entity Identifier Foundation)","url":"https://search.gleif.org/#/record/549300A0JPRWG1KI7U06","fetched_at":"2026-11-04T09:12:40Z","licence":"CC0 1.0, GLEIF"}],"lei":"549300A0JPRWG1KI7U06"},"sanctions":{"screened_lists":["EU","OFAC","UK","UN"],"lists_updated_at":{"EU":"2026-11-04T04:00:26Z","UN":"2026-11-04T04:00:33Z","OFAC":"2026-11-04T04:00:34Z","UK":"2026-11-04T04:00:46Z"},"hits":[]},"checks_left":24}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"out_of_checks: give error.upgrade_url to a human, then retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"out_of_checks","message":"This key has used its 25 free checks. Give the upgrade_url to your human. After they pay, retry with the same key.","upgrade_url":"https://checkout.example/c/9f2e..."}}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"source_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/vat/{vat}":{"get":{"operationId":"validateVat","summary":"Validate an EU VAT number via VIES. Free, rate limited.","parameters":[{"name":"vat","in":"path","required":true,"schema":{"type":"string"},"example":"FI01120389"}],"responses":{"200":{"description":"VAT result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatResult"},"example":{"vat":"FI01120389","valid":true,"name":"Nokia Oyj","address":"c/oVero-osasto PL 226 00045 NOKIA GROUP","checked_at":"2026-11-04T09:12:41Z","source":{"name":"VIES (European Commission VAT validation)","url":"https://ec.europa.eu/taxation_customs/vies/rest-api/ms/FI/vat/01120389","fetched_at":"2026-11-04T09:12:41Z"}}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"source_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/iban/{iban}":{"get":{"operationId":"validateIban","summary":"Validate an IBAN. Free, rate limited.","parameters":[{"name":"iban","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"IBAN result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IbanResult"},"example":{"iban":"EE382200221020145685","valid":true,"country":"EE","bank_code":"22","bic":"HABAEE2X","bank_name":"Swedbank AS"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sanctions":{"get":{"operationId":"screenSanctions","summary":"Screen a name against EU, UN, OFAC and UK lists. Costs 1 check. Hits are possible matches for human review.","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"threshold","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":1,"default":0.85}}],"responses":{"200":{"description":"Screening result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SanctionsResult"},{"type":"object","properties":{"checks_left":{"type":["integer","null"]}}}]}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"out_of_checks: give error.upgrade_url to a human, then retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"out_of_checks","message":"This key has used its 25 free checks. Give the upgrade_url to your human. After they pay, retry with the same key.","upgrade_url":"https://checkout.example/c/9f2e..."}}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"source_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/coverage":{"get":{"operationId":"coverage","summary":"Countries and sources covered. No key needed.","security":[],"responses":{"200":{"description":"Coverage","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key bc_live_... from POST /signup"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"enum":["unauthorized","out_of_checks","rate_limited","not_found","bad_request","source_unavailable"]},"message":{"type":"string"},"upgrade_url":{"type":"string","format":"uri"}}}}},"Source":{"type":"object","required":["name","url","fetched_at"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"fetched_at":{"type":"string","format":"date-time"},"licence":{"type":"string"}}},"Company":{"type":"object","required":["id","country","registry_id","name","former_names","status","vat_numbers","sources"],"properties":{"id":{"type":"string","examples":["FI:0112038-9"]},"country":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"former_names":{"type":"array","items":{"type":"string"}},"status":{"enum":["active","inactive","dissolved","in_liquidation","unknown"]},"status_detail":{"type":"string"},"legal_form":{"type":"string"},"incorporated_on":{"type":"string","format":"date"},"address":{"type":"string"},"vat_numbers":{"type":"array","items":{"type":"string"}},"lei":{"type":"string"},"officers":{"type":"array","items":{"type":"object","required":["name","role"],"properties":{"name":{"type":"string"},"role":{"type":"string"},"since":{"type":"string"}}}},"owners":{"type":"array","items":{"type":"object","required":["name","kind"],"properties":{"name":{"type":"string"},"share":{"type":"string"},"kind":{"enum":["person","company","unknown"]}}}},"industry":{"type":"object","required":["code","scheme"],"properties":{"code":{"type":"string"},"scheme":{"type":"string"},"label":{"type":"string"}}},"website":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"VatResult":{"type":"object","required":["vat","valid","checked_at","source"],"properties":{"vat":{"type":"string"},"valid":{"type":"boolean"},"name":{"type":"string"},"address":{"type":"string"},"checked_at":{"type":"string","format":"date-time"},"source":{"$ref":"#/components/schemas/Source"}}},"IbanResult":{"type":"object","required":["iban","valid"],"properties":{"iban":{"type":"string"},"valid":{"type":"boolean"},"country":{"type":"string"},"bank_code":{"type":"string"},"bic":{"type":"string"},"bank_name":{"type":"string"},"reason":{"type":"string"}}},"SanctionsHit":{"type":"object","required":["list","name","score","kind"],"properties":{"list":{"enum":["EU","UN","OFAC","UK"]},"name":{"type":"string"},"matched_alias":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":1},"kind":{"enum":["person","entity","vessel","other"]},"programme":{"type":"string"},"listed_on":{"type":"string"},"reference":{"type":"string"},"url":{"type":"string"}}},"SanctionsResult":{"type":"object","required":["screened_lists","lists_updated_at","hits"],"properties":{"screened_lists":{"type":"array","items":{"type":"string"}},"lists_updated_at":{"type":"object","additionalProperties":{"type":"string","format":"date-time"}},"hits":{"type":"array","items":{"$ref":"#/components/schemas/SanctionsHit"}}}},"Account":{"type":"object","description":"Plan, checks used and left, period end and a ready upgrade_url.","required":["key_prefix","plan","status","checks_used","checks_limit","checks_left","period"],"properties":{"key_prefix":{"type":"string"},"label":{"type":["string","null"]},"plan":{"enum":["free","pro"]},"status":{"type":"string"},"checks_used":{"type":"integer"},"checks_limit":{"type":"integer"},"checks_left":{"type":"integer"},"period":{"type":"string","description":"\"lifetime\" on Free, \"YYYY-MM\" on Pro"},"period_end":{"type":["string","null"],"format":"date-time"},"upgrade_url":{"type":["string","null"],"format":"uri"}}},"CheckReport":{"type":"object","required":["query","verdict","reasons","sanctions","checks_left"],"properties":{"query":{"type":"object"},"verdict":{"enum":["clear","review","fail"],"description":"fail = sanctions hit >= 0.92 or dissolved; review = weaker hit, VAT invalid, status unknown, no registry match"},"reasons":{"type":"array","items":{"type":"string"}},"company":{"$ref":"#/components/schemas/Company"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"vat":{"$ref":"#/components/schemas/VatResult"},"iban":{"$ref":"#/components/schemas/IbanResult"},"sanctions":{"$ref":"#/components/schemas/SanctionsResult"},"checks_left":{"type":["integer","null"]}}}}}}