{"openapi":"3.0.0","paths":{"/v2/pricing":{"get":{"description":"Returns pricing for a specific country.\n\nThe response includes:\n- blocks: SKUs, datapoint coverage, verification and onboarding mode prices (with an authoritative hint), and optional includedDocuments\n- Flat fields: per-datapoint availability and prices (legacy companyProfile included)\n- Company search and availableDocuments listing are free\n\nPrices are in credits (account balance units). Rates may vary by subscription plan.","operationId":"PricingController_getPricing_v2","parameters":[{"name":"countryCode","required":true,"in":"query","description":"The country code in ISO 3166-1 alpha-2 format (e.g., \"FR\" for France, \"DE\" for Germany).","schema":{"example":"FR","type":"string","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"]}}],"responses":{"200":{"description":"Pricing information retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPricingResultDTO"}}}}},"security":[{"x-api-key":[]}],"summary":"Get pricing for a country","tags":["Pricing"]}},"/v2/monitors":{"post":{"operationId":"MonitoringController_createMonitor_v2","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMonitorDto"}}}},"responses":{"201":{"description":"Monitor created or retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMonitorResponseDto"}}}},"400":{"description":"Invalid request or monitoring not supported for country"},"401":{"description":"Invalid or missing API key"}},"security":[{"x-api-key":[]}],"summary":"Add monitoring for a company","tags":["Monitors"]},"get":{"operationId":"MonitoringController_listMonitors_v2","parameters":[{"name":"companyId","required":false,"in":"query","description":"Filter by company ID","schema":{"example":"123456789","type":"string"}},{"name":"countryCode","required":false,"in":"query","description":"Filter by country code (ISO 2-letter)","schema":{"example":"DE","type":"string","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"]}},{"name":"after","required":false,"in":"query","description":"Cursor for pagination","schema":{"example":"cmfzlu1dt000j12ldeqrfszq0","type":"string"}},{"name":"first","required":false,"in":"query","description":"Number of items to fetch (default: 50)","schema":{"minimum":1,"example":25,"type":"number"}}],"responses":{"200":{"description":"List of monitors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMonitorsResponseDto"}}}},"401":{"description":"Invalid or missing API key"}},"security":[{"x-api-key":[]}],"summary":"List monitored companies","tags":["Monitors"]}},"/v2/monitors/{id}":{"get":{"operationId":"MonitoringController_getMonitor_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Monitor ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Monitor details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorDetailsResponseDto"}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Monitor not found or access denied"}},"security":[{"x-api-key":[]}],"summary":"Get monitor details","tags":["Monitors"]},"delete":{"operationId":"MonitoringController_stopMonitoring_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Monitor ID to stop","schema":{"type":"string"}}],"responses":{"204":{"description":"Monitor deleted successfully"},"401":{"description":"Invalid or missing API key"},"404":{"description":"Monitor not found or access denied"}},"security":[{"x-api-key":[]}],"summary":"Stop monitoring a company","tags":["Monitors"]}},"/v2/monitors/{id}/logs":{"get":{"operationId":"MonitoringController_getMonitorLogs_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Monitor ID","schema":{"type":"string"}},{"name":"first","required":false,"in":"query","description":"Number of items to fetch (default: 25)","schema":{"type":"number"}},{"name":"after","required":false,"in":"query","description":"Cursor for pagination","schema":{"type":"string"}}],"responses":{"200":{"description":"Monitor change logs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorLogsResponseDto"}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Monitor not found or access denied"}},"security":[{"x-api-key":[]}],"summary":"Get monitor change logs","tags":["Monitors"]}},"/v2/search":{"get":{"description":"This endpoint allows you to search for companies based on a country code and a query string.\n\nThe search can be performed using either a company legal name, commercial name, historical name, or registration number. Capabilities vary by country.\n\n**Standard Mode (stream=false or omitted):**\nReturns JSON array of results once all search sources have completed.\n\n**Streaming Mode (stream=true):**\nReturns Server-Sent Events (SSE) with progressive results as each search source completes. The endpoint emits named events:\n- `progress`: Partial results from completed sources\n- `complete`: Final results when all sources finish\n- `error`: If the search fails\n\nStreaming is beneficial for countries with multiple search sources (e.g., Germany queries both Unternehmensregister and Handelsregister), providing faster time-to-first-result.\n\nResponse times vary by country: from sub-second to up to 10 seconds.","operationId":"SearchController_searchV2_v2","parameters":[{"name":"country","required":true,"in":"query","description":"The country code in ISO 3166-1 alpha-2 format (e.g., \"FR\" for France, \"DE\" for Germany).","schema":{"example":"FR","type":"string","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"]}},{"name":"query","required":true,"in":"query","description":"The search query, which can be a company name or registration number. Note that search capabilities may vary by country, with some supporting only name or registration number searches.","schema":{"example":"Topograph","type":"string"}},{"name":"stream","required":false,"in":"query","description":"Enable streaming mode. When true, returns Server-Sent Events (SSE) with progressive results as each search source completes. Set Accept header to \"text/event-stream\" for proper streaming. When false or omitted, returns standard JSON array after all sources complete.","schema":{"example":true,"type":"boolean"}},{"name":"transliterate","required":false,"in":"query","description":"When true, user-facing string fields in the response (company names, addresses, person names, activity descriptions) are romanized from their native script to Latin characters on the way out. Internal data, cache, and billing are unaffected — only the response payload is transformed. Routing: Cyrillic/Greek/Hangul/Hebrew/Arabic/Thai via unidecode, Chinese via pinyin-pro (toneless), Japanese via kuroshiro (Hepburn).","schema":{"example":false,"type":"boolean"}}],"responses":{"200":{"description":"List of companies (JSON when stream=false, SSE when stream=true)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}},"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream with named events:\n- `progress`: Partial results as sources complete\n- `complete`: Final results when all sources finish\n- `error`: Error occurred","example":"event: progress\ndata: {\"results\":[{\"id\":\"123\",\"legalName\":\"Company A\",\"countryCode\":\"DE\",\"address\":{...}}]}\n\nevent: complete\ndata: {\"results\":[{\"id\":\"123\",\"legalName\":\"Company A\",...},{\"id\":\"456\",\"legalName\":\"Company B\",...}]}"}}}},"400":{"description":"Bad Request - Invalid search query","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"error":{"type":"object","properties":{"code":{"type":"string","example":"invalid_request"},"message":{"type":"string","example":"Query is too short. Please provide at least 2 characters for company name search"},"details":{"type":"array","items":{"type":"string"},"example":["Query must be at least 2 characters"]}}}}}}}},"500":{"description":"Internal Server Error - Search failed","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":500},"error":{"type":"object","properties":{"code":{"type":"string","example":"service_unavailable"},"message":{"type":"string","example":"An error occurred while searching. Please try again later."}}}}}}}}},"security":[{"x-api-key":[]}],"summary":"Search for companies","tags":["Search"]}},"/v2/company":{"post":{"description":"Retrieve company data and documents for a specific company.\n\nYou can either:\n1. Create a new request by providing countryCode, id, dataPoints, optional mode, and optional document IDs.\n2. Re-fetch a previous request by providing requestId (returns cached data and is not billed again).\n\nAvailable datapoints include:\n- company: core company information\n- legalRepresentatives: directors, managers, and signing officers\n- otherKeyPersons: auditors, board members, and similar roles when available\n- establishments: branches and secondary locations when available\n- shareholders: shareholder structure\n- ultimateBeneficialOwners: beneficial owner information\n- availableDocuments: list of available official documents\n- graph: ownership graph traversal\n\nLegacy companyProfile is still accepted and maps to company + legalRepresentatives for billing.\n\nModes:\n- verification (default): authoritative live registry sources\n- onboarding: cheapest compatible fast source; unsupported datapoints fail with fast_source_unavailable\n\nTo retrieve documents, first request availableDocuments to discover document IDs, then pass those IDs in the documents field of a follow-up request.","operationId":"CompanyController_getCompany_v2","parameters":[{"name":"transliterate","required":false,"in":"query","description":"If true, transliterates non-Latin strings in the response to Latin script.","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreateCompanyRequestDTO"},{"$ref":"#/components/schemas/GetCompanyRequestResultDTO"}]}}}},"responses":{"200":{"description":"Company information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCompanyResultDTO"}}}}},"security":[{"x-api-key":[]}],"summary":"Get Company Data and Documents","tags":["Data"]}},"/v2/company/{requestId}":{"get":{"description":"Retrieve the result of a previous company data request by its ID. Returns the latest available data including all subrequests (documents, additional datapoints).\n\nThis endpoint is free and will not be billed again. Use it to poll for results after creating a request via POST /v2/company.","operationId":"CompanyController_getCompanyRequest_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The request ID returned by the initial POST /v2/company call","schema":{"example":"253299d1-e8d0-4268-945b-f175f98bc114","type":"string"}},{"name":"transliterate","required":false,"in":"query","description":"If true, transliterates non-Latin strings in the response to Latin script.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Company request result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCompanyResultDTO"}}}},"404":{"description":"Request not found or does not belong to this account"}},"security":[{"x-api-key":[]}],"summary":"Get Company Request Result","tags":["Data"]}},"/v2/onboarding":{"post":{"deprecated":true,"description":"Deprecated: Use POST /v2/company with mode: \"onboarding\" instead.\n\nThis endpoint is internally routed as a companyProfile request with mode: \"onboarding\" and a 50-cent budget cap.","operationId":"CompanyOnboardingController_getOnboarding_v2","parameters":[{"name":"transliterate","required":false,"in":"query","description":"If true, transliterates non-Latin strings in the response to Latin script.","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreateOnboardingRequestDTO"},{"$ref":"#/components/schemas/GetCompanyRequestResultDTO"}]}}}},"responses":{"200":{"description":"Company onboarding information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCompanyResultDTO"}}}}},"security":[{"x-api-key":[]}],"summary":"Get Onboarding Data (Deprecated)","tags":["Data"]}},"/v2/workspaces":{"get":{"operationId":"WorkspaceController_listWorkspaces_v2","parameters":[],"responses":{"200":{"description":""}},"security":[{"x-api-key":[]}],"summary":"List all workspaces","tags":["Workspaces"]},"post":{"operationId":"WorkspaceController_createWorkspace_v2","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceDto"}}}},"responses":{"201":{"description":""}},"security":[{"x-api-key":[]}],"summary":"Create a new workspace","tags":["Workspaces"]}},"/v2/workspaces/{name}":{"patch":{"operationId":"WorkspaceController_updateWorkspace_v2","parameters":[{"name":"name","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceDto"}}}},"responses":{"200":{"description":""}},"security":[{"x-api-key":[]}],"summary":"Update a workspace","tags":["Workspaces"]},"delete":{"operationId":"WorkspaceController_deleteWorkspace_v2","parameters":[{"name":"name","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"x-api-key":[]}],"summary":"Delete a workspace","tags":["Workspaces"]}},"/v2/workspaces/usage":{"get":{"operationId":"WorkspaceController_getUsageReport_v2","parameters":[{"name":"startDate","required":false,"in":"query","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"}},{"name":"workspace","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"x-api-key":[]}],"summary":"Get usage report per workspace","tags":["Workspaces"]}},"/v2/billing/notifications/config":{"get":{"operationId":"BillingNotificationsController_getConfig_v2","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvedBillingNotificationConfigDto"}}}}},"security":[{"x-api-key":[]}],"summary":"Get resolved billing notification config (defaults merged)","tags":["Billing Notifications"]},"patch":{"operationId":"BillingNotificationsController_updateConfig_v2","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBillingNotificationConfigDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvedBillingNotificationConfigDto"}}}}},"security":[{"x-api-key":[]}],"summary":"Upsert billing notification config","tags":["Billing Notifications"]}},"/v2/billing/notifications/recent":{"get":{"operationId":"BillingNotificationsController_listRecent_v2","parameters":[{"name":"limit","required":false,"in":"query","description":"Max events to return (1–200, default 50).","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BillingNotificationEventDto"}}}}}},"security":[{"x-api-key":[]}],"summary":"List recent billing notification events","tags":["Billing Notifications"]}},"/v2/billing/notifications/workspaces/{workspaceId}/config":{"get":{"operationId":"BillingNotificationsController_getWorkspaceOverride_v2","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceBillingNotificationViewDto"}}}}},"security":[{"x-api-key":[]}],"summary":"Get resolved workspace billing notification view (override + account)","tags":["Billing Notifications"]},"patch":{"operationId":"BillingNotificationsController_upsertWorkspaceOverride_v2","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceHighUsageOverrideDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingNotificationWorkspaceOverrideDto"}}}}},"security":[{"x-api-key":[]}],"summary":"Upsert workspace high-usage override","tags":["Billing Notifications"]},"delete":{"operationId":"BillingNotificationsController_deleteWorkspaceOverride_v2","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWorkspaceOverrideResponseDto"}}}}},"security":[{"x-api-key":[]}],"summary":"Remove workspace high-usage override","tags":["Billing Notifications"]}}},"info":{"title":"Topograph","description":"The Topograph API","version":"0.1","contact":{}},"tags":[],"servers":[{"url":"https://api.topograph.co"}],"components":{"securitySchemes":{"x-api-key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PricingBlockDTO":{"type":"object","properties":{"sku":{"type":"string","description":"Block SKU identifier","example":"ita-company-data"},"datapoints":{"description":"Datapoints covered by this block","example":["company","legalRepresentatives"],"type":"array","items":{"type":"string"}},"modes":{"type":"object","description":"Pricing per mode. null means the block is not available in that mode."},"includedDocuments":{"description":"Document types included free when this block is purchased","example":["trade_register_extract"],"type":"array","items":{"type":"string"}}},"required":["sku","datapoints","modes"]},"PricingAndAvailabilityDTO":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether the data point is available for this country","example":true},"price":{"type":"number","description":"The price in credits for this data point (verification mode)","example":1.5},"pricingMode":{"type":"string","description":"Whether the price is fixed or variable (determined at request time). Omitted when fixed.","example":"variable","enum":["fixed","variable"]}},"required":["available","price"]},"GetPricingResultDTO":{"type":"object","properties":{"blocks":{"description":"Data blocks with per-mode pricing, datapoint coverage, and included documents","type":"array","items":{"$ref":"#/components/schemas/PricingBlockDTO"}},"companyProfile":{"description":"Company profile pricing (legacy, maps to company + legalRepresentatives block)","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"company":{"description":"Company data pricing","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"legalRepresentatives":{"description":"Legal representatives pricing (included in company block)","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"otherKeyPersons":{"description":"Other key persons pricing (included in company block)","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"establishments":{"description":"Establishments pricing (included in company block)","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"ultimateBeneficialOwners":{"description":"Ultimate beneficial owners pricing","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"shareholders":{"description":"Shareholders pricing","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"availableDocuments":{"description":"Available documents (always free)","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"graph":{"description":"Ownership graph pricing","allOf":[{"$ref":"#/components/schemas/PricingAndAvailabilityDTO"}]},"monitoring":{"type":"object","description":"Datapoints auto-monitored at zero cost (derived from zero-cost blocks)"}},"required":["blocks","companyProfile","ultimateBeneficialOwners","availableDocuments"]},"CreateMonitorDto":{"type":"object","properties":{"companyId":{"type":"string","description":"The company ID to monitor","example":"123456789"},"countryCode":{"type":"string","description":"The country code for the company","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"],"example":"DE"}},"required":["companyId","countryCode"]},"CreateMonitorResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the monitor","example":"cmfzlu1dt000j12ldeqrfszq0"},"companyId":{"type":"string","description":"The company ID being monitored","example":"123456789"},"countryCode":{"type":"string","description":"The country code for the monitored company","example":"DE"}},"required":["id","companyId","countryCode"]},"ListMonitorsDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Filter by company ID","example":"123456789"},"countryCode":{"type":"string","description":"Filter by country code (ISO 2-letter)","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"],"example":"DE"},"after":{"type":"string","description":"Cursor for pagination","example":"cmfzlu1dt000j12ldeqrfszq0"},"first":{"type":"number","description":"Number of items to fetch (default: 50)","example":25,"minimum":1}}},"MonitorDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the monitor","example":"cmfzlu1dt000j12ldeqrfszq0"},"companyId":{"type":"string","description":"The company ID being monitored","example":"123456789"},"countryCode":{"type":"string","description":"The country code for the monitored company","example":"DE"},"companyName":{"type":"string","description":"The legal name of the monitored company","example":"Topograph SAS","nullable":true}},"required":["id","companyId","countryCode"]},"ListMonitorsResponseDto":{"type":"object","properties":{"monitors":{"description":"List of monitored companies","type":"array","items":{"$ref":"#/components/schemas/MonitorDto"}},"total":{"type":"number","description":"Total number of monitors","example":10},"hasNextPage":{"type":"boolean","description":"Whether there is a next page available","example":true},"nextCursor":{"type":"string","description":"Cursor for the next page","example":"cmfzlu1dt000j12ldeqrfszq0"}},"required":["monitors","total","hasNextPage"]},"MonitorDetailsResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the monitor","example":"cmfzlu1dt000j12ldeqrfszq0"},"companyId":{"type":"string","description":"The company ID being monitored","example":"123456789"},"countryCode":{"type":"string","description":"The country code for the monitored company","example":"DE"},"lastFetchedAt":{"type":"string","description":"When the monitor data was last fetched","example":"2026-03-20T02:00:00.000Z","nullable":true},"createdAt":{"type":"string","description":"When the monitor was created","example":"2026-01-15T10:30:00.000Z"},"companyName":{"type":"string","description":"The legal name of the monitored company","example":"Topograph SAS","nullable":true}},"required":["id","companyId","countryCode","createdAt"]},"MonitorLogDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the log entry","example":"cmfzlu1dt000j12ldeqrfszq0"},"changeDetected":{"type":"boolean","description":"Whether a change was detected in this check","example":true},"changeCategories":{"description":"Categories of detected changes","example":["status","address"],"type":"array","items":{"type":"string"}},"fetchStatus":{"type":"string","description":"Status of the fetch operation","example":"success","enum":["success","not_found","error","error_final"]},"errorMessage":{"type":"string","description":"Error message if the fetch failed","example":null,"nullable":true},"createdAt":{"type":"string","description":"When this log entry was created","example":"2026-03-20T02:00:00.000Z"}},"required":["id","changeDetected","changeCategories","fetchStatus","createdAt"]},"MonitorLogsResponseDto":{"type":"object","properties":{"logs":{"description":"List of monitor log entries","type":"array","items":{"$ref":"#/components/schemas/MonitorLogDto"}},"hasNextPage":{"type":"boolean","description":"Whether there is a next page available","example":true},"nextCursor":{"type":"string","description":"Cursor for the next page","example":"cmfzlu1dt000j12ldeqrfszq0"}},"required":["logs","hasNextPage"]},"AddressDTO":{"type":"object","properties":{"addressLine1":{"type":"string","description":"First line of the address","example":"10 rue de la Fraternité"},"addressLine2":{"type":"string","description":"Second line of the address","example":"Topograph Building"},"city":{"type":"string","description":"City of the address","example":"Bagnolet"},"postalCode":{"type":"string","description":"Postal code of the address","example":"93170"},"region":{"type":"string","description":"Region of the address","example":"FR"},"countryCode":{"type":"string","description":"Country of the address using ISO 3166-1 alpha-2 country code","example":"FR"},"poBox":{"type":"string","description":"Post Office Box number","example":"PO Box 123"},"careOf":{"type":"string","description":"Care of (c/o) recipient","example":"c/o John Doe"},"state":{"type":"string","description":"State of the address","example":"Île-de-France"},"latitude":{"type":"number","description":"Latitude coordinate","example":59.9139},"longitude":{"type":"number","description":"Longitude coordinate","example":10.7522}},"required":["addressLine1","city","postalCode","region","countryCode","state"]},"ItalyIdentifiers":{"type":"object","properties":{"VAT":{"type":"string","description":"Partita IVA (P.IVA) - VAT registration number. Format: 11 digits (e.g., \"02580590541\"). Issued by: Agenzia delle Entrate (Revenue Agency)","example":"02580590541"},"Codice Fiscale":{"type":"string","description":"Codice Fiscale - Tax identification code. Format: 16 alphanumeric characters for individuals (e.g., \"RSSMRA70A01H501U\"), 11 digits for companies (often same as VAT). Issued by: Agenzia delle Entrate (Revenue Agency)","example":"RSSMRA70A01H501U"},"CCIAA":{"type":"string","description":"CCIAA - Camera di Commercio (Chamber of Commerce) province code. Format: 2-letter province code (e.g., \"TO\" for Torino, \"MI\" for Milano). Indicates which Chamber of Commerce the company is registered with.","example":"TO"},"REA Code":{"type":"string","description":"REA Code - Registro Economico Amministrativo (Economic Administrative Register) number. Format: Numeric (e.g., \"1234567\"). Unique within each CCIAA province. Combined with CCIAA forms a unique identifier.","example":"1234567"}},"description":"Identifiers for Italian companies (IT)"},"FranceIdentifiers":{"type":"object","properties":{"siren":{"type":"string","description":"SIREN - Système d'Identification du Répertoire des Entreprises. Format: 9 digits (e.g., \"443061841\"). Issued by: INSEE (Institut National de la Statistique et des Études Économiques). This is the primary company identifier in France.","example":"443061841"},"siret":{"type":"string","description":"SIRET - Système d'Identification du Répertoire des Établissements. Format: 14 digits = SIREN (9) + NIC (5) (e.g., \"44306184100047\"). Identifies a specific establishment (location) of a company. Issued by: INSEE.","example":"44306184100047"},"VAT":{"type":"string","description":"TVA Intracommunautaire - French VAT number. Format: FR + 2 check digits + SIREN (e.g., \"FR27443061841\"). Issued by: Direction Générale des Finances Publiques (DGFiP). Required for EU cross-border transactions.","example":"FR27443061841"},"rna":{"type":"string","description":"RNA - Répertoire National des Associations. Format: W + 9 digits (e.g., \"W751234567\"). Identifies associations registered in mainland France. Issued by: Préfecture.","example":"W751234567"},"rnaAlsaceMoselle":{"type":"string","description":"RNA Alsace-Moselle - Special identifier for associations in the Alsace-Moselle region. Format: Letter + year + code + number (e.g., \"A2002THI000075\"). These associations are registered under local law (droit local).","example":"A2002THI000075"}},"description":"Identifiers for French companies (FR)"},"MatchType":{"type":"string","enum":["id","exactLegalName","partialId","default"],"description":"The type of match that produced this result. \"id\" means a guaranteed 1:1 match from an ID-based search (e.g., VAT number, CCIAA+REA). \"exactLegalName\" means the legal name exactly matches the search query. \"partialId\" means matched by a partial identifier that is not guaranteed unique (e.g., REA without CCIAA). \"default\" is used when the exact matching criteria is unknown. Results are ordered: id > exactLegalName > partialId > default."},"MatchReason":{"type":"object","properties":{"matchType":{"description":"The type of match that produced this result. \"id\" means a guaranteed 1:1 match from an ID-based search (e.g., VAT number, CCIAA+REA). \"exactLegalName\" means the legal name exactly matches the search query. \"partialId\" means matched by a partial identifier that is not guaranteed unique (e.g., REA without CCIAA). \"default\" is used when the exact matching criteria is unknown. Results are ordered: id > exactLegalName > partialId > default.","example":"id","allOf":[{"$ref":"#/components/schemas/MatchType"}]},"identifier":{"description":"The identifier that matched this result. Present when matchType is \"id\" or \"partialId\". Shows which identifier type and value were used to find this company.","oneOf":[{"$ref":"#/components/schemas/ItalyIdentifiers","title":"IT"},{"$ref":"#/components/schemas/FranceIdentifiers","title":"FR"}],"example":{"VAT":"02580590541"}}},"required":["matchType"]},"SearchResult":{"type":"object","properties":{"address":{"description":"The legal address of the company","allOf":[{"$ref":"#/components/schemas/AddressDTO"}]},"id":{"type":"string","example":"932884117","description":"The company number. In some countries, this might be a concatenation of the registry and city (e.g., in Germany: \"Augsburg HRB 34617\"). The search function will always return a usable company number. Check the documentation to see which number format is used for each country."},"legalName":{"type":"string","description":"Legal name of the company","example":"SEMAPHORE"},"legalNameInEnglish":{"type":"string","example":"Test Display Hong Kong Trading Limited","description":"The English translation or romanization of the legal name, commonly used for international business. Particularly relevant for companies registered with non-Latin alphabet names (e.g., Chinese, Japanese, Korean, etc.)."},"country":{"type":"string","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW","US-FL","US-MA","US-NJ","US-NY","US-TX","US-DE","US-WA","US-GA","US-NV","TEST"],"example":"FR","description":"The country code in ISO 3166-1 alpha-2 format (e.g., \"FR\" for France, \"DE\" for Germany)."},"matchReason":{"description":"Match reason containing information about why this result was returned. Includes the match type and which identifier matched for ID matches.","example":{"matchType":"default"},"allOf":[{"$ref":"#/components/schemas/MatchReason"}]}},"required":["address","id","legalName","country","matchReason"]},"CreateCompanyRequestDTO":{"type":"object","properties":{"id":{"type":"string","example":"932884117","description":"The company id. In some countries, this might be a concatenation of the registry and city (e.g., in Germany: \"Augsburg HRB 34617\"). The search function will always return a usable company number. Check the documentation to see which number format is used for each country."},"countryCode":{"type":"string","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"],"example":"FR","description":"The country code in ISO 3166-1 alpha-2 format (e.g., \"FR\" for France, \"DE\" for Germany)."},"dataPoints":{"type":"array","items":{"type":"string","enum":["companyProfile","ultimateBeneficialOwners","availableDocuments","shareholders","graph","company","legalRepresentatives","otherKeyPersons","establishments"]},"example":["company","legalRepresentatives"],"description":"The data points to retrieve: company, legalRepresentatives, otherKeyPersons, establishments, shareholders, ultimateBeneficialOwners, availableDocuments, graph. Legacy: companyProfile (maps to company + legalRepresentatives for billing)."},"documents":{"type":"array","items":{"type":"string"},"example":["1c932de4-4610-5506-b48d-4e62529d58e8"],"description":"List of document IDs to retrieve. Discover these IDs by requesting the \"availableDocuments\" data point first, then pass the returned IDs here in a follow-up request."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Arbitrary key-value string pairs to associate with the request. Limits: max 50 keys, keys up to 40 chars (longer keys are skipped), values up to 500 chars (longer values are truncated)."},"graphMaxBudget":{"type":"number","example":1000,"description":"Maximum budget in credit cents for graph traversal. When the \"graph\" datapoint is requested, the traversal will stop once this budget is reached. If not provided, uses a default maximum."},"profileMaxBudget":{"type":"number","example":500,"description":"Maximum budget in credit cents for company profile retrieval. For countries with variable pricing (e.g., Hungary), the request will fail with a budget_exceeded error if the actual cost exceeds this budget. The error includes the quoted price so the user can retry with a higher budget."},"mode":{"type":"string","enum":["verification","onboarding"],"description":"Data retrieval mode. \"verification\" (default) selects authoritative live registry sources. \"onboarding\" selects the cheapest compatible fast source for form prefill and initial screening, and marks unsupported datapoints as failed with error code \"fast_source_unavailable\" when no fast source exists."},"fast":{"type":"boolean","deprecated":true,"description":"Deprecated. Use mode: \"onboarding\" instead."},"authoritative":{"type":"boolean","deprecated":true,"description":"Deprecated. Use mode instead."},"maxBudget":{"type":"number","example":200,"description":"Hard cap on total block cost in credit cents. If the resolved blocks exceed this budget, the request fails with a budget_exceeded error including the actual cost and suggestion."},"agenticEnrichment":{"type":"boolean","example":true,"description":"Enable best-effort enrichment of legal representative person details (birth date, nationality, residence address) from official publications. Belgium only. Not all fields are guaranteed — depends on publication availability. Fixed 50 cent cost per request, charged only if enrichment yields results. Introduces `enriching` datapoint status while processing is in progress."}},"required":["id","countryCode"]},"GetCompanyRequestResultDTO":{"type":"object","properties":{"requestId":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000","description":"Optional UUID that references a previous request. When provided, returns cached data from that specific request instead of fetching fresh data."}},"required":["requestId"]},"AustriaIdentifiers":{"type":"object","properties":{"companyNumber":{"type":"string","description":"Firmenbuchnummer - Company registration number. Format: 6 digits followed by a letter (e.g., \"123456A\"). Issued by: Firmenbuch (Company Register).","example":"123456A"},"VAT":{"type":"string","description":"VAT number (USt-IdNr/UID) without ATU prefix. Format: U + 8 digits (e.g., \"U12345678\"). Full format: ATU12345678. Note: VAT number is not derivable from Firmenbuchnummer and must be obtained separately.","example":"U12345678"},"zvrNumber":{"type":"string","description":"ZVR number (Vereinsregisternummer) — Central Association Register number. Format: 1-10 digits (e.g., \"432857691\"). Issued by: Zentrales Vereinsregister (BMI).","example":"432857691"},"gisaZahl":{"type":"string","description":"GISA-Zahl — Trade licence number from the Austrian Trade Information System. Format: 5-10 digits (e.g., \"10118573\"). Issued by: GISA (Gewerbeinformationssystem Austria).","example":"10118573"}},"description":"Identifiers for Austrian companies (AT)"},"BelgiumIdentifiers":{"type":"object","properties":{"enterpriseNumber":{"type":"string","description":"Enterprise Number (Ondernemingsnummer) - Unique identifier for Belgian companies. Format: 10 digits, typically formatted as 0XXX.XXX.XXX (e.g., \"0425.258.688\"). Issued by: Crossroads Bank for Enterprises (CBE).","example":"0425.258.688"},"VAT":{"type":"string","description":"VAT number (BTW nummer) without BE prefix. In Belgium, the VAT number equals the enterprise number (10 digits starting with 0). Format: 10 digits (e.g., \"0425258688\"). Full format: BE0425258688.","example":"0425258688"}},"description":"Identifiers for Belgian companies (BE)"},"SwitzerlandIdentifiers":{"type":"object","properties":{"uid":{"type":"string","description":"UID (Unternehmens-Identifikationsnummer) - Swiss company identification number. Format: CHE-XXX.XXX.XXX or CHEXXXXXXXXX (e.g., \"CHE-123.456.789\"). Issued by: Federal Statistical Office.","example":"CHE-123.456.789"}},"description":"Identifiers for Swiss companies (CH)"},"ChinaIdentifiers":{"type":"object","properties":{"uscc":{"type":"string","description":"USCC (Unified Social Credit Code) - 18-digit unified social credit code. Format: 18 alphanumeric characters (e.g., \"91110000MA01234567\"). Issued by: State Administration for Industry and Commerce.","example":"91110000MA01234567"}},"description":"Identifiers for Chinese companies (CN)"},"CyprusIdentifiers":{"type":"object","properties":{"registrationNumber":{"type":"string","description":"Registration Number - Company registration number in Cyprus. Format: Numeric identifier issued by the Registrar of Companies.","example":"123456"}},"description":"Identifiers for Cypriot companies (CY)"},"CzechiaIdentifiers":{"type":"object","properties":{"ico":{"type":"string","description":"IČO (Identifikační číslo osoby) - Company identification number. Format: 8 digits (e.g., \"12345678\"). Issued by: Czech Statistical Office.","example":"12345678"},"dic":{"type":"string","description":"DIČ (Daňové identifikační číslo) - Tax identification number. Format: CZ prefix + 8-10 digits (e.g., \"CZ12345678\"). For companies, this is typically CZ + IČO.","example":"CZ12345678"},"VAT":{"type":"string","description":"VAT number (DIČ) without CZ prefix. Format: 8-10 digits. For companies, this is typically the same as IČO.","example":"12345678"}},"description":"Identifiers for Czech companies (CZ)"},"GermanyIdentifiers":{"type":"object","properties":{"hrb":{"type":"string","description":"HRB - Handelsregister B (Commercial Register B) number for companies. Format: \"City HRB XXXXXX\" or \"City (District) HRB XXXXXX\" (e.g., \"München HRB 228960\"). Issued by: Local court (Amtsgericht).","example":"München HRB 228960"},"hra":{"type":"string","description":"HRA - Handelsregister A (Commercial Register A) number for sole traders. Format: \"City HRA XXXXXX\" or \"City (District) HRA XXXXXX\". Issued by: Local court (Amtsgericht).","example":"Berlin HRA 12345"},"vr":{"type":"string","description":"VR - Vereinsregister (Association Register) number. Format: \"City VR XXXXXX\" or \"City (District) VR XXXXXX\". Issued by: Local court (Amtsgericht).","example":"Berlin (Charlottenburg) VR 33464"},"pr":{"type":"string","description":"PR - Partnerschaftsregister (Partnership Register) number. Format: \"City PR XXXXXX\" or \"City (District) PR XXXXXX\". Issued by: Local court (Amtsgericht).","example":"Hamburg PR 12345"},"gnr":{"type":"string","description":"GnR/GNR - Genossenschaftsregister (Cooperative Register) number. Format: \"City GnR XXXXXX\" or \"City (District) GnR XXXXXX\". Issued by: Local court (Amtsgericht).","example":"München GnR 12345"}},"description":"Identifiers for German companies (DE)"},"DenmarkIdentifiers":{"type":"object","properties":{"cvr":{"type":"string","description":"CVR Number (Central Business Register) - Company registration number. Format: 8 digits (e.g., \"12345678\"). Issued by: Danish Business Authority (Erhvervsstyrelsen).","example":"12345678"},"VAT":{"type":"string","description":"VAT number (Momsregistreringsnummer) without DK prefix. Format: 8 digits (same as CVR). In Denmark, CVR number equals VAT number.","example":"12345678"},"enhedsNummer":{"type":"string","description":"Unit number (Enhedsnummer) - Internal CVR identifier for the business unit. Format: up to 10 digits (e.g., \"4001459308\"). Issued by: Danish Business Authority (Erhvervsstyrelsen).","example":"4001459308"}},"description":"Identifiers for Danish companies (DK)"},"EstoniaIdentifiers":{"type":"object","properties":{"registryCode":{"type":"string","description":"Registrikood - Registry code. Format: 8 digits (e.g., \"12345678\"). Issued by: Business Register (Äriregister).","example":"12345678"},"VAT":{"type":"string","description":"VAT number (KMKR number) without EE prefix. Format: 9 digits. Available from Estonian Business Registry (kmkr_number field).","example":"123456789"}},"description":"Identifiers for Estonian companies (EE)"},"FinlandIdentifiers":{"type":"object","properties":{"businessId":{"type":"string","description":"Business ID (Y-Tunnus) - Finnish business identification number. Format: 7 digits, hyphen, 1 digit (e.g., \"1234567-8\"). Issued by: Finnish Business Information System (YTJ).","example":"1234567-8"},"VAT":{"type":"string","description":"VAT number (ALV-numero) without FI prefix. Format: 8 digits (Business ID without hyphen). In Finland, VAT = FI + Business ID without dash.","example":"12345678"}},"description":"Identifiers for Finnish companies (FI)"},"GuernseyIdentifiers":{"type":"object","properties":{"registryNumber":{"type":"string","description":"Registry Number - Company registration number. Format: Various prefixes followed by numbers (e.g., \"CMP10001\", \"FND167\", \"NP2\"). Prefixes include: CMP (Companies), FND (Foundations), NP (Non-Profits), CH (Charities). Issued by: Guernsey Registry.","example":"CMP10001"}},"description":"Identifiers for Guernsey companies (GG)"},"HongKongIdentifiers":{"type":"object","properties":{"brn":{"type":"string","description":"BRN (Business Registration Number) - Company registration number. Format: 8 digits (e.g., \"12345678\"). Issued by: Companies Registry.","example":"12345678"}},"description":"Identifiers for Hong Kong companies (HK)"},"CroatiaIdentifiers":{"type":"object","properties":{"mbs":{"type":"string","description":"MBS (Matični broj subjekta) - Company registration number. Format: 9 digits, often with leading zero (e.g., \"010006782\"). Issued by: Court Register (Sudski registar).","example":"010006782"},"oib":{"type":"string","description":"OIB (Osobni identifikacijski broj) - Tax identification number. Format: 11 digits (e.g., \"09520995772\"). Issued by: Tax Administration.","example":"09520995772"},"VAT":{"type":"string","description":"VAT number (PDV broj) without HR prefix. Format: 11 digits (same as OIB). In Croatia, OIB equals VAT number.","example":"09520995772"}},"description":"Identifiers for Croatian companies (HR)"},"HungaryIdentifiers":{"type":"object","properties":{"companyNumber":{"type":"string","description":"Company Number - Company registration number. Format: Numeric identifier issued by the Court of Registration.","example":"12345678"},"taxNumber":{"type":"string","description":"Tax Number (Adószám) - Full tax identification number. Format: 11 digits, often shown as xxxxxxxx-y-zz. The first 8 digits form the EU VAT number (HU + first 8 digits).","example":"12345678290"},"VAT":{"type":"string","description":"VAT number (ÁFA szám) without HU prefix. Format: First 8 digits of the tax number. In Hungary, VAT = HU + first 8 digits of tax number.","example":"12345678"},"evnyRegistrationNumber":{"type":"string","description":"EVNY Registration Number (Nyilvántartási szám) for sole traders. Format: 8 digits. Sole traders are registered in the EVNY registry, separate from the Cégjegyzék (company registry).","example":"12345678"}},"description":"Identifiers for Hungarian companies (HU)"},"IcelandIdentifiers":{"type":"object","properties":{"kennitala":{"type":"string","description":"Kennitala (National ID / Registration number). Format: 10 digits (e.g., \"5602151420\"). Issued by: Ríkisskattstjóri (Directorate of Internal Revenue).","example":"5602151420"}},"description":"Identifiers for Icelandic companies (IS)"},"IrelandIdentifiers":{"type":"object","properties":{"companyNumber":{"type":"string","description":"Company Number - Company registration number. Format: Numeric identifier issued by the Companies Registration Office (CRO).","example":"123456"}},"description":"Identifiers for Irish companies (IE)"},"JerseyIdentifiers":{"type":"object","properties":{"companyNumber":{"type":"string","description":"Company Number - Company registration number. Format: Numeric identifier issued by the Jersey Financial Services Commission.","example":"123456"}},"description":"Identifiers for Jersey companies (JE)"},"LiechtensteinIdentifiers":{"type":"object","properties":{"flNumber":{"type":"string","description":"FL Number - Company registration number. Format: Numeric identifier issued by the Office of Justice.","example":"123456"}},"description":"Identifiers for Liechtenstein companies (LI)"},"LuxembourgIdentifiers":{"type":"object","properties":{"rcs":{"type":"string","description":"RCS (Registre de Commerce et des Sociétés) - Company registration number. Format: Numeric identifier issued by the Trade and Companies Register.","example":"B123456"},"VAT":{"type":"string","description":"VAT number (Numéro de TVA intracommunautaire) without LU prefix. Format: 8 digits (e.g., 32326416).","example":"32326416"}},"description":"Identifiers for Luxembourg companies (LU)"},"LatviaIdentifiers":{"type":"object","properties":{"registrationNumber":{"type":"string","description":"Registration Number - Company registration number. Format: Numeric identifier issued by the Register of Enterprises.","example":"12345678901"}},"description":"Identifiers for Latvian companies (LV)"},"MonacoIdentifiers":{"type":"object","properties":{"rci":{"type":"string","description":"RCI (Registre du Commerce et de l'Industrie) - Company registration number. Format: Numeric identifier issued by the Trade and Industry Register.","example":"123456"}},"description":"Identifiers for Monégasque companies (MC)"},"MaltaIdentifiers":{"type":"object","properties":{"companyNumber":{"type":"string","description":"Company Number - Company registration number. Format: Numeric identifier issued by the Malta Business Registry.","example":"C12345"}},"description":"Identifiers for Maltese companies (MT)"},"MauritiusIdentifiers":{"type":"object","properties":{"brn":{"type":"string","description":"BRN (Business Registration Number) - Company registration number. Format: Numeric identifier issued by the Registrar of Companies.","example":"C123456"}},"description":"Identifiers for Mauritian companies (MU)"},"NetherlandsIdentifiers":{"type":"object","properties":{"kvk":{"type":"string","description":"KVK (Kamer van Koophandel) - Chamber of Commerce number. Format: Numeric identifier issued by the Chamber of Commerce.","example":"12345678"},"RSIN":{"type":"string","description":"RSIN (Rechtspersonen en Samenwerkingsverbanden Informatienummer) - Legal Entities and Partnerships Information Number. Format: 9 digits. Issued by: Netherlands Tax Administration. Used as the base for VAT number for legal entities.","example":"123456789"},"VAT":{"type":"string","description":"VAT number (BTW nummer) without NL prefix. Format: RSIN + B + 2 check digits (for legal entities) or 9 digits + B + 2 check digits (for sole proprietors). Full format: NL[RSIN]B[checkdigits] or NL[9digits]B[checkdigits]. Note: VAT number cannot be derived from KVK or RSIN alone (requires check digits).","example":"123456789B01"}},"description":"Identifiers for Dutch companies (NL)"},"NorwayIdentifiers":{"type":"object","properties":{"organizationNumber":{"type":"string","description":"Organization Number (Organisasjonsnummer) - Company registration number. Format: 9 digits, optionally formatted with spaces or dots (e.g., \"123 456 789\" or \"123.456.789\"). Issued by: Brønnøysund Register Centre.","example":"123456789"}},"description":"Identifiers for Norwegian companies (NO)"},"PolandIdentifiers":{"type":"object","properties":{"krs":{"type":"string","description":"KRS (Krajowy Rejestr Sądowy) - National Court Register number. Format: 1-10 digits, padded with leading zeros to 10 digits (e.g., \"0000123456\"). Issued by: National Court Register.","example":"0000123456"},"nip":{"type":"string","description":"NIP (Numer Identyfikacji Podatkowej) - Tax identification number. Format: 10 digits (e.g., \"1234567890\"). Issued by: Tax Office.","example":"1234567890"},"regon":{"type":"string","description":"REGON (Rejestr Gospodarki Narodowej) - Statistical number. Format: 9 digits (short) or 14 digits (long) (e.g., \"123456789\" or \"12345678901234\"). Issued by: Central Statistical Office.","example":"123456789"},"VAT":{"type":"string","description":"VAT number (Numer Identyfikacji Podatkowej dla VAT) without PL prefix. In Poland, the VAT number equals the NIP. Format: 10 digits (same as NIP).","example":"1234567890"}},"description":"Identifiers for Polish companies (PL)"},"PortugalIdentifiers":{"type":"object","properties":{"NIF":{"type":"string","description":"NIF (Número de Identificação Fiscal) - Tax identification number. Format: 9 digits (8 digits + 1 check digit). For companies, the first digit is typically 5. Issued by: Autoridade Tributária e Aduaneira (Tax and Customs Authority).","example":"517116022"},"VAT":{"type":"string","description":"VAT number (Número de Identificação de Valor Acrescentado) without PT prefix. In Portugal, the VAT number equals the NIF. Format: 9 digits (same as NIF).","example":"517116022"}},"description":"Identifiers for Portuguese companies (PT)"},"RomaniaIdentifiers":{"type":"object","properties":{"cui":{"type":"string","description":"CUI (Cod Unic de Înregistrare) - Unique registration code. Format: Numeric identifier issued by the National Trade Register Office.","example":"12345678"},"registrationNumber":{"type":"string","description":"Registration Number (Număr de ordine în Registrul Comerțului). Format: J/F/C + County Code + Number + Year (e.g., J40/123/2024).","example":"J40/123/2024"},"VAT":{"type":"string","description":"VAT number (Cod de TVA) without RO prefix. Format: 2-10 digits (same as CUI). In Romania, CUI IS the VAT number.","example":"12345678"}},"description":"Identifiers for Romanian companies (RO)"},"SpainIdentifiersDTO":{"type":"object","properties":{"nif":{"type":"string","description":"NIF/CIF (Número de Identificación Fiscal)","example":"A82511361"},"VAT":{"type":"string","description":"VAT number (IVA) without ES prefix. In Spain, this equals the NIF.","example":"A82511361"}},"required":["nif","VAT"]},"SwedenIdentifiers":{"type":"object","properties":{"organizationNumber":{"type":"string","description":"Organization Number (Organisationsnummer) - Company registration number. Format: 10 digits, optionally formatted with hyphen (e.g., \"123456-7890\") or prefixed with SE (e.g., \"SE123456789001\"). Issued by: Swedish Companies Registration Office (Bolagsverket).","example":"1234567890"},"VAT":{"type":"string","description":"VAT number (Momsregistreringsnummer) without SE prefix. Format: Organisationsnummer (10 digits) + \"01\" (2 check digits) = 12 digits total. Example: \"559285421901\" (from org number \"5592854219\").","example":"559285421901"}},"description":"Identifiers for Swedish companies (SE)"},"SlovakiaIdentifiers":{"type":"object","properties":{"ico":{"type":"string","description":"IČO (Identifikačné číslo organizácie) - Company identification number. Format: 8 digits (e.g., \"12345678\"). Issued by: Slovak Statistical Office.","example":"12345678"}},"description":"Identifiers for Slovak companies (SK)"},"SloveniaIdentifiers":{"type":"object","properties":{"registrationNumber":{"type":"string","description":"Matična številka (Registration number). Format: 10 digits (e.g., \"5000681000\"). Issued by: AJPES (Slovenian Business Register).","example":"5000681000"},"taxNumber":{"type":"string","description":"Davčna številka (Tax number). Format: 8 digits (e.g., \"10000024\"). Issued by: Financial Administration of the Republic of Slovenia (FURS).","example":"10000024"},"VAT":{"type":"string","description":"VAT identification number. Format: SI + 8 digits (e.g., \"SI10000024\"). Issued by: Financial Administration of the Republic of Slovenia (FURS).","example":"SI10000024"}},"description":"Identifiers for Slovenian companies (SI)"},"UnitedKingdomIdentifiers":{"type":"object","properties":{"companyNumber":{"type":"string","description":"Company Number - Company registration number. Format: 8 digits (e.g., \"12345678\"). Issued by: Companies House.","example":"12345678"}},"description":"Identifiers for UK companies (GB)"},"BVIIdentifiers":{"type":"object","properties":{"companyNumber":{"type":"string","description":"Company Number - Company registration number. Format: Numeric identifier issued by the BVI Financial Services Commission.","example":"123456"}},"description":"Identifiers for BVI companies (VG)"},"CountryIdentifiersDTO":{"type":"object","properties":{"VAT":{"type":"string","description":"Partita IVA (P.IVA) - VAT registration number. Format: 11 digits (e.g., \"02580590541\"). Issued by: Agenzia delle Entrate (Revenue Agency)","example":"02580590541"},"Codice Fiscale":{"type":"string","description":"Codice Fiscale - Tax identification code. Format: 16 alphanumeric characters for individuals (e.g., \"RSSMRA70A01H501U\"), 11 digits for companies (often same as VAT). Issued by: Agenzia delle Entrate (Revenue Agency)","example":"RSSMRA70A01H501U"},"CCIAA":{"type":"string","description":"CCIAA - Camera di Commercio (Chamber of Commerce) province code. Format: 2-letter province code (e.g., \"TO\" for Torino, \"MI\" for Milano). Indicates which Chamber of Commerce the company is registered with.","example":"TO"},"REA Code":{"type":"string","description":"REA Code - Registro Economico Amministrativo (Economic Administrative Register) number. Format: Numeric (e.g., \"1234567\"). Unique within each CCIAA province. Combined with CCIAA forms a unique identifier.","example":"1234567"}}},"TaxIdVerificationDTO":{"type":"object","properties":{"status":{"type":"string","enum":["verified","unverified","unavailable"],"description":"Verification status of the tax ID","example":"verified"},"verifiedAt":{"type":"string","description":"ISO date when the tax ID was verified","example":"2024-01-15T10:30:00Z"},"verifiedName":{"type":"string","description":"Company name returned by the validation service (e.g., VIES)","example":"TOPOGRAPH SAS"},"verifiedAddress":{"type":"string","description":"Address returned by the validation service (e.g., VIES)","example":"123 RUE DE PARIS, 75001 PARIS"},"consultationNumber":{"type":"string","description":"VIES consultation number (requestIdentifier) - the legal proof of validation for audit purposes","example":"WAPIAAAAW1234567890"}},"required":["status"]},"TaxIdDTO":{"type":"object","properties":{"type":{"type":"string","description":"Tax ID type (Stripe-aligned)","example":"eu_vat"},"value":{"type":"string","description":"Tax ID value WITHOUT country prefix","example":"27443061841"},"country":{"type":"string","description":"ISO2 country code","example":"FR"},"verification":{"description":"Verification details for the tax ID","allOf":[{"$ref":"#/components/schemas/TaxIdVerificationDTO"}]}},"required":["type","value","country"]},"CompanyStatusDetailsDTO":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","UNDER_INSOLVENCY_PROCEEDING","CLOSED","UNKNOWN"],"example":"ACTIVE","description":"The standardized status of the company"},"closureReason":{"type":"string","enum":["BANKRUPTCY","LIQUIDATION","MERGER","ACQUISITION","VOLUNTARY_DISSOLUTION","ADMINISTRATIVE_DISSOLUTION","COURT_ORDER","SPLIT","OTHER","UNKNOWN"],"example":"BANKRUPTCY","description":"The reason for company closure, if applicable"},"closureDate":{"type":"string","example":"2024-01-15","description":"The date when the company was closed, if applicable"},"insolvencyStartDate":{"type":"string","example":"2023-12-01","description":"The date when insolvency proceedings started, if applicable"},"additionalInfo":{"type":"string","example":"Company entered voluntary liquidation due to retirement of owner","description":"Additional information about the status"}},"required":["status"]},"CompanyStatusDTO":{"type":"object","properties":{"localName":{"type":"string","example":"active","description":"The local status of the company in the local language"},"active":{"type":"boolean","example":true,"description":"Indicates if the company is active."},"statusDetails":{"description":"Detailed status information including closure reasons and dates","allOf":[{"$ref":"#/components/schemas/CompanyStatusDetailsDTO"}]}},"required":["localName"]},"LegalFormEnum":{"type":"string","enum":["Sole Proprietorship","Partnership","Limited Liability Company","Corporation","Nonprofit Organization","Cooperative","Government-Owned Entity","Branch or Representative Office","Trust","Other"],"description":"The standardized legal form of the company."},"LegalFormDTO":{"type":"object","properties":{"localName":{"type":"string","example":"EURL, entreprise unipersonnelle à responsabilité limitée","description":"The local legal form of the company, in the local language"},"englishTranslation":{"type":"string","example":"Single Member Limited Liability Company","description":"The English translation of the local legal form."},"semaphoreStandard":{"example":"Limited Liability Company","description":"The standardized legal form of the company.","deprecated":true,"allOf":[{"$ref":"#/components/schemas/LegalFormEnum"}]},"standardized":{"example":"Limited Liability Company","description":"The standardized legal form of the company.","allOf":[{"$ref":"#/components/schemas/LegalFormEnum"}]},"iso20275Code":{"type":"string","example":"F8DD","description":"The ISO 20275 Entity Legal Form code for the company."},"isAIEnriched":{"type":"boolean","description":"True when englishTranslation, standardized, and iso20275Code were AI-inferred rather than sourced directly from the registry."}}},"MonetaryAmountDTO":{"type":"object","properties":{"amount":{"type":"number","description":"The numeric amount of money.","example":1000},"currency":{"type":"string","description":"The ISO 4217 currency code (e.g., EUR, USD).","example":"EUR"},"formatted":{"type":"string","description":"Formatted string representation of the monetary amount in the local format","example":"1000.00 €"}},"required":["amount","currency","formatted"]},"EmployeeCountDTO":{"type":"object","properties":{"exact":{"type":"number","example":150,"description":"The exact number of employees, if known"},"min":{"type":"number","example":100,"description":"The minimum number of employees in a range"},"max":{"type":"number","example":200,"description":"The maximum number of employees in a range"},"lastUpdated":{"type":"string","example":"2024-03-15","description":"The date when the employee count was last updated"},"isEstimate":{"type":"boolean","example":false,"description":"Indicates if the employee count is an estimate"}}},"CompanyDTO":{"type":"object","properties":{"id":{"type":"string","description":"The id of the company, see documentation.","example":"932884117"},"countryCode":{"type":"string","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW","US-FL","US-MA","US-NJ","US-NY","US-TX","US-DE","US-WA","US-GA","US-NV","TEST"],"description":"The  ISO 3166-1 alpha-2 country code of the company registration country","example":"FR"},"identifiers":{"description":"Company identifiers such as VAT number, tax code, and registry codes. Available fields vary by country. See country-specific schemas for details.","oneOf":[{"$ref":"#/components/schemas/ItalyIdentifiers","title":"IT"},{"$ref":"#/components/schemas/FranceIdentifiers","title":"FR"}],"allOf":[{"$ref":"#/components/schemas/CountryIdentifiersDTO"}]},"taxId":{"description":"Tax identification number with validation proof. For EU VAT, the value does NOT include the country prefix (e.g., \"27443061841\" not \"FR27443061841\").","allOf":[{"$ref":"#/components/schemas/TaxIdDTO"}]},"legalName":{"type":"string","example":"Topograph","description":"The legal name of the company."},"legalNameInEnglish":{"type":"string","example":"Test Display Hong Kong Trading Limited","description":"The English translation or romanization of the legal name, commonly used for international business. Particularly relevant for companies registered with non-Latin alphabet names (e.g., Chinese, Japanese, Korean, etc.)."},"commercialNames":{"example":["Topograph","TopographHQ"],"description":"An array of commercial names or trading names used by the company.","type":"array","items":{"type":"string"}},"legacyLegalNames":{"example":["Semaphore","SemaphoreHQ"],"description":"An array of legacy legal names used by the company.","type":"array","items":{"type":"string"}},"legacyCommercialNames":{"example":["Semaphore","SemaphoreHQ"],"description":"An array of legacy commercial names used by the company.","type":"array","items":{"type":"string"}},"status":{"description":"The status of the company, including local status and whether it is active.","allOf":[{"$ref":"#/components/schemas/CompanyStatusDTO"}]},"registrationDate":{"type":"string","example":"2024-04-22","description":"The registration date of the company with the trade register or other authorities."},"incorporationDate":{"type":"string","example":"2024-04-15","description":"The incorporation date when the company was legally incorporated or founded. This may differ from the registration date, as companies are often incorporated before being registered with trade authorities."},"legalForm":{"description":"The legal form of the company, including local and standard forms.","allOf":[{"$ref":"#/components/schemas/LegalFormDTO"}]},"capital":{"description":"The share capital of the company.","allOf":[{"$ref":"#/components/schemas/MonetaryAmountDTO"}]},"activities":{"type":"object","description":"A dictionary of activity classifications","example":{"NACE":[{"code":"62.01","description":"Computer programming activities"}],"ISIC":[{"code":"J620","description":"Computer programming, consultancy and related activities"}]},"additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/CompanyActivityItemDTO"}}},"activityDescription":{"type":"string","description":"A text description of the company activities","example":"Development of software solutions and IT consulting services"},"legalAddress":{"description":"The address of the company.","allOf":[{"$ref":"#/components/schemas/AddressDTO"}]},"phones":{"example":["+33123456789","+33987654321"],"description":"An array of phone numbers for the company in E.164 format (e.g., +33123456789 for France, +1234567890 for USA).","type":"array","items":{"type":"string"}},"website":{"type":"string","example":"https://www.example.com","description":"The official website URL of the company."},"employeeCount":{"description":"The employee count information for the company.","allOf":[{"$ref":"#/components/schemas/EmployeeCountDTO"}]}},"required":["countryCode"]},"PersonNameDTO":{"type":"object","properties":{"title":{"type":"string","description":"Title of the person (e.g., Mr., Mrs., Dr.)"},"firstName":{"type":"string","description":"First name of the person"},"middleName":{"type":"string","description":"Middle name of the person"},"lastName":{"type":"string","description":"Last name of the person"},"fullName":{"type":"string","description":"Full name of the person"},"suffix":{"type":"string","description":"Suffix of the name (e.g., Jr., Sr., III)"}},"required":["fullName"]},"BirthDateDTO":{"type":"object","properties":{"day":{"type":"number","description":"Day of birth (1-31)","example":15},"month":{"type":"number","description":"Month of birth (1-12), where January is 1","example":7},"year":{"type":"number","description":"Year of birth","example":1980}}},"RangeDto":{"type":"object","properties":{"lower":{"type":"number","description":"Lower bound of the range","example":25},"upper":{"type":"number","description":"Upper bound of the range","example":50}},"required":["lower","upper"]},"PercentageDetailDto":{"type":"object","properties":{"type":{"type":"string","description":"Type of percentage detail (shares, voting rights)","enum":["shares","voting-rights"],"example":"shares"},"percentageRange":{"description":"Range of control as a lower and upper bound","example":{"lower":25,"upper":50},"allOf":[{"$ref":"#/components/schemas/RangeDto"}]},"percentageValue":{"type":"number","description":"Exact percentage of control","example":30},"monetaryAmount":{"description":"Monetary amount of shares controlled","allOf":[{"$ref":"#/components/schemas/MonetaryAmountDTO"}]},"numberOfShares":{"type":"number","description":"Number of shares controlled","example":1000},"nature":{"type":"string","description":"Indicates whether the control is direct or indirect","enum":["direct","indirect"],"example":"direct"}},"required":["type","percentageRange","percentageValue","monetaryAmount"]},"ControlDTO":{"type":"object","properties":{"types":{"type":"array","description":"Types of control held by the beneficial owner","items":{"type":"string","enum":["ownership-of-shares","voting-rights","appoint-and-remove-directors","significant-influence-or-control"]},"example":["ownership-of-shares"]},"description":{"type":"string","description":"Description of why the person is of significant control","example":"The person holds more than 50% of the shares in the company."},"details":{"description":"Details about the percentage of control","type":"array","items":{"$ref":"#/components/schemas/PercentageDetailDto"}}},"required":["types","description","details"]},"UltimateBeneficialOwnerDTO":{"type":"object","properties":{"gender":{"type":"string","description":"Gender of the person","enum":["Male","Female","Other","PreferNotToSay"],"example":"Female"},"name":{"description":"Full name of the person","example":{"fullName":"John Doe"},"allOf":[{"$ref":"#/components/schemas/PersonNameDTO"}]},"birthDate":{"description":"Birth date of the person","example":{"day":15,"month":7,"year":1980},"allOf":[{"$ref":"#/components/schemas/BirthDateDTO"}]},"birthAddress":{"description":"Birth address of the person","example":{"country":"FR","city":"Paris","street":"1 Rue de Rivoli","postalCode":"75001"},"allOf":[{"$ref":"#/components/schemas/AddressDTO"}]},"nationality":{"type":"string","description":"Nationality ISO2 country code of the person","example":"US"},"residenceAddress":{"description":"Residence address of the person","allOf":[{"$ref":"#/components/schemas/AddressDTO"}]},"identifiers":{"type":"array","description":"List of identifiers for the person (e.g., codice fiscale)","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}}},"entityId":{"type":"string","description":"Unique identifier to track the same person or company across different roles (legal representatives, shareholders, UBOs, etc.). Since data is retrieved from multiple registries, the same entity may appear with slightly different names or details. This ID allows you to identify that \"John Smith\" as a legal representative is the same person as \"J. Smith\" listed as a shareholder.","example":"person_001"},"control":{"description":"Details of control held by the beneficial owner","example":{"controlType":"ownership-of-shares","description":"The person holds more than 50% of the shares in the company.","percentageDetails":[{"type":"shares","range":{"lower":50,"upper":75}}],"additionalDetails":"Direct ownership of shares"},"allOf":[{"$ref":"#/components/schemas/ControlDTO"}]}},"required":["gender","name","birthDate","birthAddress","nationality","residenceAddress","control"]},"RoleEnum":{"type":"string","enum":["Director","Manager","Employee","Chief Executive Officer","Chief Financial Officer","Chief Operating Officer","President","Vice President","Secretary","Treasurer","Legal Advisor","General Counsel","Partner","Associate","Other","Chairman of the Board","Board Member","Managing Director","Executive Director","Non-Executive Director","General Partner","Managing Partner","Limited Partner","Administrator","Liquidator","Receiver","Owner","Chairman","Auditor","Authorized Signatory"],"description":"The standardized role of the individual."},"RoleDTO":{"type":"object","properties":{"localName":{"type":"string","description":"The local role name in the local language","example":"Directeur"},"englishTranslation":{"type":"string","description":"The role name in English","example":"Director"},"iso5009Code":{"type":"string","description":"The ISO 5009 role code","example":"GIDXNF"},"semaphoreStandard":{"example":"Director","description":"The standardized role of the individual.","deprecated":true,"allOf":[{"$ref":"#/components/schemas/RoleEnum"}]},"standardized":{"example":"Director","description":"The standardized role of the individual.","allOf":[{"$ref":"#/components/schemas/RoleEnum"}]}},"required":["standardized"]},"PhysicalPersonBaseDTO":{"type":"object","properties":{"gender":{"type":"string","description":"Gender of the person","enum":["Male","Female","Other","PreferNotToSay"],"example":"Female"},"name":{"description":"Full name of the person","example":{"fullName":"John Doe"},"allOf":[{"$ref":"#/components/schemas/PersonNameDTO"}]},"birthDate":{"description":"Birth date of the person","example":{"day":15,"month":7,"year":1980},"allOf":[{"$ref":"#/components/schemas/BirthDateDTO"}]},"birthAddress":{"description":"Birth address of the person","example":{"country":"FR","city":"Paris","street":"1 Rue de Rivoli","postalCode":"75001"},"allOf":[{"$ref":"#/components/schemas/AddressDTO"}]},"nationality":{"type":"string","description":"Nationality ISO2 country code of the person","example":"US"},"residenceAddress":{"description":"Residence address of the person","allOf":[{"$ref":"#/components/schemas/AddressDTO"}]},"identifiers":{"type":"array","description":"List of identifiers for the person (e.g., codice fiscale)","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}}}},"required":["gender","name","birthDate","birthAddress","nationality","residenceAddress"]},"RepresentationModeDTO":{"type":"object","properties":{"mode":{"type":"string","description":"Whether this representative can act alone (sole) or must act jointly with others (joint)","enum":["sole","joint"],"example":"sole"},"minimumSignatories":{"type":"number","description":"Minimum number of signatories required for joint representation (e.g. 2 for \"Kollektivzeichnung zu zweien\")","example":2},"namedCoSigners":{"description":"Named co-signers this person must act with for joint representation","example":["Kázsmér János"],"type":"array","items":{"type":"string"}}},"required":["mode"]},"LegalRepresentativeDTO":{"type":"object","properties":{"entityId":{"type":"string","description":"Unique identifier to track the same person or company across different roles (legal representatives, shareholders, UBOs, etc.). Since data is retrieved from multiple registries, the same entity may appear with slightly different names or details. This ID allows you to identify that \"John Smith\" as a legal representative is the same person as \"J. Smith\" listed as a shareholder.","example":"person_001"},"role":{"description":"The role of the legal representative","allOf":[{"$ref":"#/components/schemas/RoleDTO"}]},"startDate":{"type":"string","description":"The start date of the legal representative's role","example":"2022-01-01"},"endDate":{"type":"string","description":"The end date of the legal representative's role (if applicable)","example":"2023-12-31"},"type":{"type":"string","description":"The type of the legal representative (individual or company)","enum":["individual","company"],"example":"individual"},"individual":{"description":"Details of the individual legal representative","allOf":[{"$ref":"#/components/schemas/PhysicalPersonBaseDTO"}]},"company":{"description":"Details of the company legal representative","allOf":[{"$ref":"#/components/schemas/CompanyDTO"}]},"representedBy":{"description":"When type is COMPANY: the physical person who represents/acts on behalf of the company (e.g., \"représentant permanent\" in French)","allOf":[{"$ref":"#/components/schemas/PhysicalPersonBaseDTO"}]},"representationMode":{"description":"How this representative can bind the company: sole (can act alone) or joint (must act with others)","allOf":[{"$ref":"#/components/schemas/RepresentationModeDTO"}]}},"required":["type"]},"ShareholderDTO":{"type":"object","properties":{"entityId":{"type":"string","description":"Unique identifier to track the same person or company across different roles (legal representatives, shareholders, UBOs, etc.). Since data is retrieved from multiple registries, the same entity may appear with slightly different names or details. This ID allows you to identify that \"John Smith\" as a legal representative is the same person as \"J. Smith\" listed as a shareholder.","example":"person_001"},"type":{"type":"string","description":"The type of the shareholder (individual or company)","enum":["individual","company"],"example":"individual"},"individual":{"description":"Details of the individual shareholder","allOf":[{"$ref":"#/components/schemas/PhysicalPersonBaseDTO"}]},"company":{"description":"Details of the company shareholder","allOf":[{"$ref":"#/components/schemas/CompanyDTO"}]},"sharePercentage":{"type":"number","description":"The percentage of shares owned by the shareholder","example":25.5},"numberOfShares":{"type":"number","description":"The absolute number of shares owned by the shareholder","example":1000},"nominalCapitalHeld":{"description":"Total nominal (stated) capital value held by this shareholder. This is the face value or par value of all shares owned, calculated as numberOfShares × parValuePerShare. For example, if a shareholder owns 1000 shares with a par value of €10 each, nominalCapitalHeld would be €10,000. This value represents the legal capital contribution recorded in company documents, not the market value or actual amount paid.","readOnly":true,"allOf":[{"$ref":"#/components/schemas/MonetaryAmountDTO"}]},"paidInAmount":{"description":"Total actual amount paid by the shareholder for their shares, including any share premium over the nominal/par value. This represents the real money invested. For example, if shares with €10,000 nominal value were purchased for €15,000, the paidInAmount would be €15,000. In Italy this corresponds to \"valore versato\", in Germany to \"eingezahltes Kapital\". This field captures the actual capital contribution to the company.","allOf":[{"$ref":"#/components/schemas/MonetaryAmountDTO"}]}},"required":["type"]},"EstablishmentDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the establishment","example":"EST-001"},"name":{"type":"string","description":"The name of the establishment","example":"Main Office"},"creationDate":{"type":"string","description":"The creation date of the establishment","example":"2020-01-15"},"endDate":{"type":"string","description":"The closing date of the establishment (if applicable)","example":"2023-12-31"},"active":{"type":"boolean","description":"Whether the establishment is currently active","example":true},"address":{"description":"The address of the establishment","allOf":[{"$ref":"#/components/schemas/AddressDTO"}]}},"required":["name"]},"OtherKeyPersonRoleEnum":{"type":"string","enum":["Board Member","Non-Executive Director","Independent Director","Advisory Board Member","Board Observer","Auditor","Compliance Officer","Data Protection Officer","Money Laundering Reporting Officer","Secretary","Supervisor","Supervisory Board Member","C-Level Executive","Registered Agent","Other"],"description":"The standardized role of the individual."},"OtherKeyPersonRoleDTO":{"type":"object","properties":{"localName":{"type":"string","description":"The local role name in the local language","example":"Commissaire aux comptes"},"englishTranslation":{"type":"string","description":"The role name in English","example":"Auditor"},"semaphoreStandard":{"example":"Board Member","description":"The standardized role of the individual.","deprecated":true,"allOf":[{"$ref":"#/components/schemas/OtherKeyPersonRoleEnum"}]},"standardized":{"example":"Board Member","description":"The standardized role of the individual.","allOf":[{"$ref":"#/components/schemas/OtherKeyPersonRoleEnum"}]}},"required":["standardized"]},"OtherKeyPersonDTO":{"type":"object","properties":{"entityId":{"type":"string","description":"Unique identifier to track the same person or company across different roles (legal representatives, shareholders, UBOs, etc.). Since data is retrieved from multiple registries, the same entity may appear with slightly different names or details. This ID allows you to identify that \"John Smith\" as a legal representative is the same person as \"J. Smith\" listed as a shareholder.","example":"person_001"},"role":{"description":"The role of the other key person","allOf":[{"$ref":"#/components/schemas/OtherKeyPersonRoleDTO"}]},"startDate":{"type":"string","description":"The start date of the role","example":"2022-01-01"},"endDate":{"type":"string","description":"The end date of the role (if applicable)","example":"2023-12-31"},"type":{"type":"string","enum":["individual","company"],"description":"The type of the other key person (individual or company)","example":"individual"},"individual":{"description":"Details if the other key person is an individual","allOf":[{"$ref":"#/components/schemas/PhysicalPersonBaseDTO"}]},"company":{"description":"Details if the other key person is a company","allOf":[{"$ref":"#/components/schemas/CompanyDTO"}]}},"required":["type"]},"AvailableDocumentDTO":{"type":"object","properties":{"format":{"type":"string","description":"Document format (ISO format)","example":"PDF"},"description":{"type":"string","description":"Document description","example":"Uncertified trade register extract, provided by the French INPI"},"estimatedDeliverySeconds":{"type":"number","description":"Estimated delivery time in seconds","example":0},"name":{"type":"string","description":"Document name in the original language","example":"Certificat INPI"},"id":{"type":"string","description":"Document ID for this specific company document. Pass this ID to the \"documents\" array in a follow-up request when you want to download it.","example":"1c932de4-4610-5506-b48d-4e62529d58e8"},"date":{"format":"date-time","type":"string","description":"Document date","example":"2024-06-30T23:59:59Z"},"type":{"type":"string","description":"Document type","enum":["financial_statement","uncertified_trade_register_extract","certified_trade_register_extract","ubo_extract","status","trade_register_history","official_publication","annual_return","certificate_of_good_standing","unknown","other"],"example":"uncertified_trade_register_extract"},"price":{"type":"number","description":"Document price, in credits","example":3}},"required":["name","id","type"]},"DocumentDTO":{"type":"object","properties":{"id":{"type":"string","description":"Document ID returned by the \"availableDocuments\" data point for this specific company document.","example":"1c932de4-4610-5506-b48d-4e62529d58e8"},"url":{"type":"string","description":"Temporary document download URL with a 15-minute lifetime. If the URL expires, you can request the same document again within 24 hours without being charged.","example":"https://example.com/download/document123"},"blobName":{"type":"string","description":"Blob name","example":"document123.pdf"}},"required":["id","url","blobName"]},"CompanyActivityItemDTO":{"type":"object","properties":{"code":{"type":"string","description":"The activity code","example":"62.01"},"description":{"type":"string","description":"The description of the activity","example":"Computer programming activities"},"isAIInferred":{"type":"boolean","description":"Indicates whether the activity code comes from an official source or has been inferred by AI","example":true}},"required":["code","description","isAIInferred"]},"CompnanyActivitiesDTO":{"type":"object","properties":{"ISIC":{"description":"The ISIC activity codes of the company, as deep as possible","type":"array","items":{"$ref":"#/components/schemas/CompanyActivityItemDTO"}},"NACE":{"description":"The NACE activity codes of the company, as deep as possible","type":"array","items":{"$ref":"#/components/schemas/CompanyActivityItemDTO"}}}},"DocumentWithUrlDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Document name in the local language of the country where it was issued"},"description":{"type":"string","description":"Document description in English"},"format":{"type":"string"},"estimatedDeliverySeconds":{"type":"number"},"url":{"type":"string"},"pdfUrl":{"type":"string","description":"URL to converted PDF version (when original document is XML)"},"blobName":{"type":"string"},"price":{"type":"number","description":"Fixed price in cents"},"priceMarkup":{"type":"number","description":"Price markup percentage"},"date":{"type":"string"}},"required":["id","name","format"]},"PeriodDateDTO":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"day":{"type":"number"}}},"PeriodDTO":{"type":"object","properties":{"startDate":{"$ref":"#/components/schemas/PeriodDateDTO"},"endDate":{"$ref":"#/components/schemas/PeriodDateDTO"}}},"FinancialRatiosDTO":{"type":"object","properties":{"currentRatio":{"type":"number"},"quickRatio":{"type":"number"},"debtToEquity":{"type":"number"},"netProfitMargin":{"type":"number"},"returnOnEquity":{"type":"number"},"revenueGrowth":{"type":"number"}}},"FinancialInsightDTO":{"type":"object","properties":{"category":{"type":"string","enum":["liquidity","profitability","solvency","efficiency","growth","risk"]},"title":{"type":"string"},"description":{"type":"string"},"riskLevel":{"type":"string","enum":["low","medium","high","critical"]},"metricValue":{"type":"string"},"recommendation":{"type":"string"}},"required":["category","title","description","riskLevel"]},"FinancialTrendsDTO":{"type":"object","properties":{"revenueDirection":{"type":"string","enum":["increasing","stable","decreasing","unknown"]},"profitabilityDirection":{"type":"string","enum":["improving","stable","declining","unknown"]},"debtDirection":{"type":"string","enum":["decreasing","stable","increasing","unknown"]}},"required":["revenueDirection","profitabilityDirection","debtDirection"]},"FinancialAnalysisDTO":{"type":"object","properties":{"summary":{"type":"string","description":"Executive summary (2-3 sentences)"},"narrativeAnalysis":{"type":"string","description":"Detailed multi-paragraph narrative analysis"},"healthScore":{"type":"number","description":"Overall health score (1-10)"},"overallRisk":{"type":"string","enum":["low","medium","high","critical"]},"ratios":{"$ref":"#/components/schemas/FinancialRatiosDTO"},"insights":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInsightDTO"}},"strengths":{"type":"array","items":{"type":"string"}},"concerns":{"type":"array","items":{"type":"string"}},"trends":{"$ref":"#/components/schemas/FinancialTrendsDTO"}},"required":["summary","narrativeAnalysis","healthScore","overallRisk","ratios","insights","strengths","concerns","trends"]},"ExtractedFinancialDataDTO":{"type":"object","properties":{"fiscalYear":{"type":"object","description":"Fiscal year period covered by the financial statement"},"approvalDate":{"type":"string"},"currency":{"type":"string"},"accountingStandard":{"type":"string","enum":["IFRS","French GAAP","US GAAP","Swiss GAAP","Lux GAAP","Other"]},"statementType":{"type":"string","enum":["consolidated","simplified"]},"analysis":{"description":"AI-generated financial analysis and insights","allOf":[{"$ref":"#/components/schemas/FinancialAnalysisDTO"}]},"incomeStatement":{"type":"object"},"balanceSheet":{"type":"object"}}},"FinancialStatementDTO":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Document name in the local language of the country where it was issued"},"description":{"type":"string","description":"Document description in English"},"format":{"type":"string"},"estimatedDeliverySeconds":{"type":"number"},"url":{"type":"string"},"pdfUrl":{"type":"string","description":"URL to converted PDF version (when original document is XML)"},"blobName":{"type":"string"},"price":{"type":"number","description":"Fixed price in cents"},"priceMarkup":{"type":"number","description":"Price markup percentage"},"date":{"type":"string"},"period":{"$ref":"#/components/schemas/PeriodDTO"},"extractedFinancialData":{"description":"Extracted financial data from the document (only available after document is downloaded and parsed)","allOf":[{"$ref":"#/components/schemas/ExtractedFinancialDataDTO"}]}},"required":["id","name","format"]},"ArticleOfAssociationDTO":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Document name in the local language of the country where it was issued"},"description":{"type":"string","description":"Document description in English"},"format":{"type":"string"},"estimatedDeliverySeconds":{"type":"number"},"url":{"type":"string"},"pdfUrl":{"type":"string","description":"URL to converted PDF version (when original document is XML)"},"blobName":{"type":"string"},"price":{"type":"number","description":"Fixed price in cents"},"priceMarkup":{"type":"number","description":"Price markup percentage"},"date":{"type":"string"}},"required":["id","name","format"]},"DocumentsDTO":{"type":"object","properties":{"tradeRegisterExtract":{"$ref":"#/components/schemas/DocumentWithUrlDto"},"certifiedTradeRegisterExtract":{"$ref":"#/components/schemas/DocumentWithUrlDto"},"financialStatements":{"type":"array","items":{"$ref":"#/components/schemas/FinancialStatementDTO"}},"articlesOfAssociation":{"type":"array","items":{"$ref":"#/components/schemas/ArticleOfAssociationDTO"}},"ultimateBeneficialOwnersCertificate":{"$ref":"#/components/schemas/DocumentWithUrlDto"},"officialPublications":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithUrlDto"}},"annualReturns":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithUrlDto"}},"certificateOfGoodStanding":{"$ref":"#/components/schemas/DocumentWithUrlDto"},"otherDocuments":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithUrlDto"}},"lastFiscalYearFinancialStatement":{"$ref":"#/components/schemas/DocumentWithUrlDto"}},"required":["tradeRegisterExtract","certifiedTradeRegisterExtract","financialStatements","articlesOfAssociation","ultimateBeneficialOwnersCertificate","lastFiscalYearFinancialStatement"]},"GraphIndividualDTO":{"type":"object","properties":{"name":{"type":"object","description":"Full name of the person"},"birthDate":{"type":"object","description":"Date of birth, if available"},"nationality":{"type":"string","description":"Nationality ISO2 country code","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW","US-FL","US-MA","US-NJ","US-NY","US-TX","US-DE","US-WA","US-GA","US-NV","TEST"]}},"required":["name"]},"GraphCompanyDTO":{"type":"object","properties":{"id":{"type":"string","description":"Company registration ID/number (optional for individuals)"},"legalName":{"type":"string","description":"Legal name of the company"},"countryCode":{"type":"string","description":"Country of registration","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW","US-FL","US-MA","US-NJ","US-NY","US-TX","US-DE","US-WA","US-GA","US-NV","TEST"]}},"required":["legalName","countryCode"]},"GraphNodeFlagsDTO":{"type":"object","properties":{"isRoot":{"type":"boolean","description":"True if this is the root/target company being analyzed"},"isUbo":{"type":"boolean","description":"True if this individual has >25% ownership and qualifies as a UBO (individuals only)"},"isUboProxy":{"type":"boolean","description":"True if this company is the ultimate controlling entity of the target company (companies only)"},"uboCalculationMethod":{"type":"array","description":"Methods that qualified this individual as UBO (only when isUbo is true)","items":{"type":"string","enum":["accumulation","domination"]}},"status":{"type":"string","description":"Status of the node during graph building (pending = loading, found = complete)","enum":["pending","found","not_found","error","search_resolved","placeholder"]}}},"GraphNodeDTO":{"type":"object","properties":{"nodeId":{"type":"string","description":"A unique identifier for the node in the graph (for graph traversal)"},"type":{"type":"string","description":"Whether this is an individual person or a company","enum":["individual","company"]},"individual":{"description":"Individual person data (only populated when type is individual)","allOf":[{"$ref":"#/components/schemas/GraphIndividualDTO"}]},"company":{"description":"Company data (only populated when type is company)","allOf":[{"$ref":"#/components/schemas/GraphCompanyDTO"}]},"totalOwnershipPercentage":{"type":"number","description":"The total calculated ownership percentage of the root company (0-100)"},"flags":{"description":"Flags indicating special properties of this node","allOf":[{"$ref":"#/components/schemas/GraphNodeFlagsDTO"}]}},"required":["nodeId","type"]},"GraphEdgeDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the edge"},"fromId":{"type":"string","description":"ID of the company being owned"},"toId":{"type":"string","description":"ID of the entity that owns shares (shareholder)"},"percentage":{"type":"number","description":"Ownership percentage (0-100)"},"source":{"type":"string","description":"Source information about where this relationship was found"}},"required":["id","fromId","toId"]},"GraphMetadataDTO":{"type":"object","properties":{"stoppedReason":{"type":"string","description":"Reason why graph traversal stopped","enum":["completed","budget_exhausted","max_depth_reached","max_nodes_reached","timeout"]},"amountSpent":{"type":"number","description":"Total amount spent in credit cents during traversal"},"companiesFetched":{"type":"number","description":"Number of companies successfully fetched during traversal"},"companiesSkipped":{"type":"number","description":"Number of companies skipped (due to budget or limits)"}},"required":["stoppedReason","amountSpent","companiesFetched","companiesSkipped"]},"EnhancedGraphResultDTO":{"type":"object","properties":{"nodes":{"description":"All entities in the ownership structure","type":"array","items":{"$ref":"#/components/schemas/GraphNodeDTO"}},"edges":{"description":"All ownership relationships","type":"array","items":{"$ref":"#/components/schemas/GraphEdgeDTO"}},"mermaidDiagram":{"type":"string","description":"Mermaid diagram representation"},"description":{"type":"string","description":"Human-readable description of the graph"},"metadata":{"description":"Metadata about the graph traversal process","allOf":[{"$ref":"#/components/schemas/GraphMetadataDTO"}]}},"required":["nodes","edges"]},"ShareholderNodeDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the node"},"name":{"type":"string","description":"Name of the shareholder"},"type":{"type":"string","description":"Type of shareholder (individual or company)","enum":["individual","company"]},"countryCode":{"type":"string","description":"Country code","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG","IM","KY","US-FL","US-MA","US-TX","US-DE","UA","US-NY","US-NJ","US-WA","US-GA","US-NV","TEST"]},"percentage":{"type":"number","description":"Ownership percentage"},"children":{"description":"Child nodes (recursive structure)","type":"array","items":{"$ref":"#/components/schemas/ShareholderNodeDTO"}},"error":{"type":"string","description":"Error message if node processing failed"}},"required":["id","name","type","children"]},"DataSourceDocumentDTO":{"type":"object","properties":{"name":{"type":"string","description":"Name of the supporting document","example":"Statuts constitutifs"},"date":{"type":"string","description":"Date of the document","example":"2020-03-15"},"reason":{"type":"string","description":"Brief explanation of why this document is pertinent for the analysis","example":"Most recent confirmation statement showing 100% ownership by KCA Deutag International 3 Limited"}},"required":["name"]},"DataSourceDTO":{"type":"object","properties":{"type":{"type":"string","description":"How the data was obtained: live_from_registry (fresh API call), cached_from_registry (database copy), inferred (simple derivation from registry data), ai_analysis (complex AI analysis from documents), private_source (paid data)","enum":["live_from_registry","cached_from_registry","inferred","ai_analysis","private_source"],"example":"live_from_registry"},"register":{"type":"string","description":"Machine-readable register code. Omitted for inferred and ai_analysis types.","example":"inpi"},"documents":{"description":"Supporting documents (for ai_analysis type)","type":"array","items":{"$ref":"#/components/schemas/DataSourceDocumentDTO"}},"analysis":{"type":"string","description":"AI reasoning summary explaining how the data was derived (for ai_analysis type)","example":"Inferred from 2021 confirmation statement showing 100% ownership by KCA Deutag International 3 Limited"}},"required":["type"]},"EntitySourcesDTO":{"type":"object","properties":{"entityId":{"type":"string","description":"Stable entity identifier matching the underlying entity (e.g. ShareholderDTO.entityId, GraphNodeDTO.nodeId for individuals). Lets consumers look up sources by entity rather than relying on positional alignment."},"fields":{"type":"object","description":"Per-field data sources, keyed by field name."},"overall":{"description":"Holistic source for this entity (e.g. an AI agent narrative explaining how this shareholder was traced). Distinct from per-field sources, which describe each individual datapoint.","allOf":[{"$ref":"#/components/schemas/DataSourceDTO"}]}}},"EntityListSourcesDTO":{"type":"object","properties":{"overall":{"description":"List-level source. Describes how the entire list was assembled (e.g. AI reconstruction summary covering all shareholders). The analysis field carries the prose; documents lists the supporting documents.","allOf":[{"$ref":"#/components/schemas/DataSourceDTO"}]},"limitations":{"description":"Structured list of gaps the AI agent flagged about building this list (e.g. unparseable documents, missing share-pledge agreements).","type":"array","items":{"type":"string"}},"items":{"description":"Per-entity sources, 1:1 by array index with the corresponding entity array (e.g. shareholders, ultimateBeneficialOwners).","type":"array","items":{"$ref":"#/components/schemas/EntitySourcesDTO"}}}},"GraphSourcesDTO":{"type":"object","properties":{"nodes":{"type":"object","description":"Per-node provenance, keyed by graph nodeId (graph.nodes[i].nodeId). Today only company nodes that had AI-reconstructed shareholders get an entry. Future per-node provenance types (UBO calculation reasoning, edge sources, etc.) become sibling fields inside each GraphNodeSourcesDTO."}}},"DataSourcesDTO":{"type":"object","properties":{"company":{"type":"object","description":"Per-field data sources for company profile fields. Keys are field names, values describe the source."},"shareholders":{"description":"Sources for the shareholders list. Carries list-level overall (e.g. AI reconstruction summary), limitations the agent flagged, and per-entity sources 1:1 by index with the shareholders array.","allOf":[{"$ref":"#/components/schemas/EntityListSourcesDTO"}]},"ultimateBeneficialOwners":{"description":"Sources for the ultimate beneficial owners list. Same shape as shareholders.","allOf":[{"$ref":"#/components/schemas/EntityListSourcesDTO"}]},"legalRepresentatives":{"description":"Sources for the legal representatives list. Same shape as shareholders.","allOf":[{"$ref":"#/components/schemas/EntityListSourcesDTO"}]},"establishments":{"description":"Sources for the establishments list. Same shape as shareholders.","allOf":[{"$ref":"#/components/schemas/EntityListSourcesDTO"}]},"otherKeyPersons":{"description":"Sources for the other key persons list. Same shape as shareholders.","allOf":[{"$ref":"#/components/schemas/EntityListSourcesDTO"}]},"graph":{"description":"Sources specific to the ownership graph (per-graph-node provenance). Each company node in the graph that had its shareholders AI-reconstructed carries its own EntityListSourcesDTO under nodes[<nodeId>].shareholders. Distinct from dataSources.shareholders, which is scoped to the result-level shareholders list (the root company only).","allOf":[{"$ref":"#/components/schemas/GraphSourcesDTO"}]}}},"DataPointStatusSucceeded":{"type":"object","properties":{"cost":{"type":"number","description":"The cost in credits for this data point or document","example":10},"costMarkup":{"type":"number","description":"The percentage markup when final cost is not yet known","example":20},"status":{"type":"string","description":"The data point completed successfully","enum":["succeeded"],"example":"succeeded"},"authoritative":{"type":"boolean","description":"Whether the data comes from an authoritative official registry source","example":true}},"required":["status"]},"DataPointStatusInProgress":{"type":"object","properties":{"cost":{"type":"number","description":"The cost in credits for this data point or document","example":10},"costMarkup":{"type":"number","description":"The percentage markup when final cost is not yet known","example":20},"status":{"type":"string","description":"The data point is being retrieved","enum":["in_progress"],"example":"in_progress"}},"required":["status"]},"DataPointStatusEnriching":{"type":"object","properties":{"cost":{"type":"number","description":"The cost in credits for this data point or document","example":10},"costMarkup":{"type":"number","description":"The percentage markup when final cost is not yet known","example":20},"status":{"type":"string","description":"The data point has been retrieved and is being enriched with additional details","enum":["enriching"],"example":"enriching"}},"required":["status"]},"DataPointError":{"type":"object","properties":{"code":{"type":"string","description":"Error code identifying the type of failure","example":"resource_not_found","enum":["resource_not_found","service_unavailable","processing_failed","invalid_request","datapoint_not_supported","fast_source_unavailable","onboarding_timeout","insufficient_funds"]},"message":{"type":"string","description":"User-friendly error message explaining the failure","example":"The requested company was not found. Please verify the registration number and try again."},"details":{"type":"array","description":"Additional specific error details when applicable","items":{"type":"string"},"example":["Query must be at least 2 characters"]}},"required":["code","message"]},"DataPointStatusFailed":{"type":"object","properties":{"cost":{"type":"number","description":"The cost in credits for this data point or document","example":10},"costMarkup":{"type":"number","description":"The percentage markup when final cost is not yet known","example":20},"status":{"type":"string","description":"The data point retrieval failed","enum":["failed"],"example":"failed"},"error":{"description":"Error information for the failed data point","allOf":[{"$ref":"#/components/schemas/DataPointError"}]},"errors":{"type":"array","description":"Deprecated - use error.message instead","deprecated":true,"items":{"type":"string"}}},"required":["status","error"]},"DataStatus":{"type":"object","properties":{"dataPoints":{"type":"object","description":"Retrieval status of data points","additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/DataPointStatusSucceeded"},{"$ref":"#/components/schemas/DataPointStatusInProgress"},{"$ref":"#/components/schemas/DataPointStatusEnriching"},{"$ref":"#/components/schemas/DataPointStatusFailed"}],"discriminator":{"propertyName":"status","mapping":{"succeeded":"#/components/schemas/DataPointStatusSucceeded","in_progress":"#/components/schemas/DataPointStatusInProgress","enriching":"#/components/schemas/DataPointStatusEnriching","failed":"#/components/schemas/DataPointStatusFailed"}}}},"documents":{"type":"object","description":"Retrieval status of documents","additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/DataPointStatusSucceeded"},{"$ref":"#/components/schemas/DataPointStatusInProgress"},{"$ref":"#/components/schemas/DataPointStatusEnriching"},{"$ref":"#/components/schemas/DataPointStatusFailed"}],"discriminator":{"propertyName":"status","mapping":{"succeeded":"#/components/schemas/DataPointStatusSucceeded","in_progress":"#/components/schemas/DataPointStatusInProgress","enriching":"#/components/schemas/DataPointStatusEnriching","failed":"#/components/schemas/DataPointStatusFailed"}}}}},"required":["dataPoints","documents"]},"RequestMetadataDTO":{"type":"object","properties":{"companyId":{"type":"string","example":"932884117","description":"The requested company id."},"country":{"type":"string","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"],"example":"FR","description":"The requested country code."},"requestId":{"type":"string","example":"request-12345","description":"The unique identifier for the request."},"dataPoints":{"type":"array","items":{"type":"string"}},"documents":{"type":"array","items":{"type":"string"}},"dataStatus":{"description":"Indicates the status of data points and documents associated with the company. It states if the data has been retrieved, if a job is in progress for asynchronous data, or if a job there was an error.","allOf":[{"$ref":"#/components/schemas/DataStatus"}]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value string pairs provided at request creation time and echoed back in responses and webhooks."},"enrichmentReport":{"type":"string","description":"A human-readable summary of the agentic enrichment step, explaining what additional data was found or why enrichment could not provide more details. Only present when agenticEnrichment was requested."},"companyLegalName":{"type":"string","description":"The legal name of the company, if known from search results."},"workspace":{"type":"object","description":"The workspace associated with this request. Only present if the account uses workspaces."}},"required":["country","dataPoints","documents"]},"CompanyRelationshipDTO":{"type":"object","properties":{"relation":{"type":"string","enum":["mergedFrom","mergedInto","acquired","acquiredBy","demergedFrom","demergedTo","spunOffFrom","spunOffTo","assetTransferFrom","assetTransferTo","other"]},"company":{"$ref":"#/components/schemas/CompanyDTO"},"effectiveDate":{"type":"string","description":"Legal effective date if known (YYYY-MM-DD)"},"description":{"type":"string"}},"required":["relation","company"]},"GetCompanyResultDTO":{"type":"object","properties":{"request":{"description":"The request","allOf":[{"$ref":"#/components/schemas/RequestMetadataDTO"}]},"company":{"description":"The main profile information of the company, including, if available, details such as name, registration number, address, and other core data.","allOf":[{"$ref":"#/components/schemas/CompanyDTO"}]},"ultimateBeneficialOwners":{"description":"The persons of significant control of the company, including, if available, their name, nationality, and other relevant details.","type":"array","items":{"$ref":"#/components/schemas/UltimateBeneficialOwnerDTO"}},"legalRepresentatives":{"description":"The legal representatives of the company, which can be either individuals or companies.","type":"array","items":{"$ref":"#/components/schemas/LegalRepresentativeDTO"}},"shareholders":{"description":"The shareholders of the company, which can be either individuals or companies.","type":"array","items":{"$ref":"#/components/schemas/ShareholderDTO"}},"establishments":{"description":"The establishments of the company, including physical locations where business activities are conducted.","type":"array","items":{"$ref":"#/components/schemas/EstablishmentDTO"}},"otherKeyPersons":{"description":"Other key persons associated with the company who do not have legal signing authority, such as board members, auditors, and compliance officers.","type":"array","items":{"$ref":"#/components/schemas/OtherKeyPersonDTO"}},"graph":{"type":"object"},"documents":{"$ref":"#/components/schemas/DocumentsDTO"},"companyRelationships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyRelationshipDTO"}},"dataSources":{"description":"Per-field data source provenance for each entity. Keys are field names, values describe the origin of the data.","allOf":[{"$ref":"#/components/schemas/DataSourcesDTO"}]},"enrichmentReport":{"type":"string","description":"Human-readable summary of enrichment results when agenticEnrichment was requested."}},"required":["request","company"]},"CreateOnboardingRequestDTO":{"type":"object","properties":{"id":{"type":"string","example":"932884117","description":"The company id. In some countries, this might be a concatenation of the registry and city (e.g., in Germany: \"Augsburg HRB 34617\"). The search function will always return a usable company number. Check the documentation to see which number format is used for each country."},"countryCode":{"type":"string","enum":["AT","BE","BG","CH","CN","CZ","CY","DE","DK","EE","ES","FI","FR","GB","GG","GR","HK","HR","HU","IE","IS","IT","JE","LI","LU","LV","MC","MT","MU","NL","NO","PL","PT","RO","SE","SG","SI","SK","VG"],"example":"FR","description":"The country code in ISO 3166-1 alpha-2 format (e.g., \"FR\" for France, \"DE\" for Germany)."},"dataPoints":{"type":"array","items":{"type":"string","enum":["companyProfile"]},"description":"The data points to retrieve. Only companyProfile is supported for onboarding."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Arbitrary key-value string pairs to associate with the request. Limits: max 50 keys, keys up to 40 chars (longer keys are skipped), values up to 500 chars (longer values are truncated)."}},"required":["id","countryCode"]},"CreateWorkspaceDto":{"type":"object","properties":{"name":{"type":"string","description":"Workspace identifier — unique within the account.","example":"branch-paris","pattern":"^[a-zA-Z0-9_-]+$","maxLength":64},"legalName":{"type":"string","description":"Display-friendly legal name used in reporting and invoices.","example":"Acme Paris SAS","maxLength":255}},"required":["name","legalName"]},"UpdateWorkspaceDto":{"type":"object","properties":{"legalName":{"type":"string","description":"New display-friendly legal name.","example":"Acme Paris SAS","maxLength":255}}},"LowBalanceTierDto":{"type":"object","properties":{"tier":{"type":"string","description":"Severity tier name. Must be unique within the array.","enum":["warning","critical","depleted"],"example":"warning"},"cents":{"type":"number","description":"Threshold in cents (integer, same currency as the account). A notification fires when the account balance drops at or below this value.","example":100000,"minimum":0}},"required":["tier","cents"]},"HighUsageTierDto":{"type":"object","properties":{"tier":{"type":"string","description":"Severity tier name. Must be unique within the array.","enum":["warning","critical"],"example":"warning"},"cents":{"type":"number","description":"Spend threshold in cents over the rolling period. A notification fires when the rolling-period spend is at or above this value.","example":100000,"minimum":0}},"required":["tier","cents"]},"ResolvedBillingNotificationConfigDto":{"type":"object","properties":{"lowBalanceEnabled":{"type":"boolean","description":"Master toggle for low-balance notifications.","example":false},"lowBalanceEmailEnabled":{"type":"boolean","description":"Route low-balance notifications via email.","example":true},"lowBalanceWebhookEnabled":{"type":"boolean","description":"Route low-balance notifications via webhook.","example":true},"lowBalanceTiers":{"description":"Resolved low-balance tiers.","type":"array","items":{"$ref":"#/components/schemas/LowBalanceTierDto"}},"globalHighUsageEnabled":{"type":"boolean","description":"Master toggle for global (account-aggregate) high-usage notifications.","example":false},"globalHighUsageEmailEnabled":{"type":"boolean","description":"Route global high-usage notifications via email.","example":true},"globalHighUsageWebhookEnabled":{"type":"boolean","description":"Route global high-usage notifications via webhook.","example":true},"globalHighUsagePeriodMinutes":{"type":"number","description":"Rolling window, in minutes, for global high-usage evaluation.","example":1440},"globalHighUsageTiers":{"description":"Resolved global high-usage tiers.","type":"array","items":{"$ref":"#/components/schemas/HighUsageTierDto"}},"highUsageEnabled":{"type":"boolean","description":"Master toggle for per-workspace high-usage notifications.","example":false},"highUsageEmailEnabled":{"type":"boolean","description":"Route per-workspace high-usage notifications via email.","example":true},"highUsageWebhookEnabled":{"type":"boolean","description":"Route per-workspace high-usage notifications via webhook.","example":true},"highUsagePeriodMinutes":{"type":"number","description":"Rolling window, in minutes, for per-workspace high-usage evaluation.","example":1440},"highUsageTiers":{"description":"Resolved per-workspace high-usage tiers (applied as defaults to every workspace).","type":"array","items":{"$ref":"#/components/schemas/HighUsageTierDto"}},"autoTopupNotificationsEnabled":{"type":"boolean","description":"Master toggle for auto-topup outcome notifications.","example":false},"autoTopupEmailEnabled":{"type":"boolean","description":"Route auto-topup notifications via email.","example":true},"autoTopupWebhookEnabled":{"type":"boolean","description":"Route auto-topup notifications via webhook.","example":true}},"required":["lowBalanceEnabled","lowBalanceEmailEnabled","lowBalanceWebhookEnabled","lowBalanceTiers","globalHighUsageEnabled","globalHighUsageEmailEnabled","globalHighUsageWebhookEnabled","globalHighUsagePeriodMinutes","globalHighUsageTiers","highUsageEnabled","highUsageEmailEnabled","highUsageWebhookEnabled","highUsagePeriodMinutes","highUsageTiers","autoTopupNotificationsEnabled","autoTopupEmailEnabled","autoTopupWebhookEnabled"]},"UpdateBillingNotificationConfigDto":{"type":"object","properties":{"lowBalanceEnabled":{"type":"boolean","description":"Master toggle for low-balance notifications. Defaults to false on new accounts (strictly opt-in).","example":true},"lowBalanceEmailEnabled":{"type":"boolean","description":"Route low-balance notifications via email. Applied when lowBalanceEnabled is true.","example":true},"lowBalanceWebhookEnabled":{"type":"boolean","description":"Route low-balance notifications via webhook. Applied when lowBalanceEnabled is true.","example":true},"lowBalanceTiers":{"description":"Ordered list of low-balance tiers. Each tier fires once when the account balance drops at or below its `cents` threshold. Tier names must be unique.","minItems":1,"maxItems":10,"type":"array","items":{"$ref":"#/components/schemas/LowBalanceTierDto"}},"globalHighUsageEnabled":{"type":"boolean","description":"Master toggle for global (account-aggregate) high-usage notifications. Defaults to false on new accounts.","example":false},"globalHighUsageEmailEnabled":{"type":"boolean","description":"Route global high-usage notifications via email.","example":true},"globalHighUsageWebhookEnabled":{"type":"boolean","description":"Route global high-usage notifications via webhook.","example":true},"globalHighUsagePeriodMinutes":{"type":"number","description":"Rolling window, in minutes, used to sum account-aggregate spend when evaluating global high-usage tiers. Min 5 (5 minutes), max 43200 (30 days).","example":1440,"minimum":5,"maximum":43200},"globalHighUsageTiers":{"description":"Global high-usage tiers. Fires when the sum of spend across ALL workspaces (plus the account-wide bucket) over the rolling window meets-or-exceeds `cents`.","minItems":1,"maxItems":5,"type":"array","items":{"$ref":"#/components/schemas/HighUsageTierDto"}},"highUsageEnabled":{"type":"boolean","description":"Master toggle for per-workspace high-usage notifications. These thresholds are applied individually to each workspace; a workspace can override them via the workspace-override endpoint.","example":false},"highUsageEmailEnabled":{"type":"boolean","description":"Route per-workspace high-usage notifications via email.","example":true},"highUsageWebhookEnabled":{"type":"boolean","description":"Route per-workspace high-usage notifications via webhook.","example":true},"highUsagePeriodMinutes":{"type":"number","description":"Rolling window, in minutes, used to sum per-workspace spend when evaluating high-usage tiers. Min 5, max 43200.","example":1440,"minimum":5,"maximum":43200},"highUsageTiers":{"description":"Per-workspace high-usage tiers. Fires when a single workspace's spend over the rolling window meets-or-exceeds `cents`.","minItems":1,"maxItems":5,"type":"array","items":{"$ref":"#/components/schemas/HighUsageTierDto"}},"autoTopupNotificationsEnabled":{"type":"boolean","description":"Master toggle for auto-topup outcome notifications (succeeded / failed). Distinct from Account.autoTopupEnabled, which controls the charge itself. Defaults to false on new accounts.","example":false},"autoTopupEmailEnabled":{"type":"boolean","description":"Route auto-topup outcome notifications via email.","example":true},"autoTopupWebhookEnabled":{"type":"boolean","description":"Route auto-topup outcome notifications via webhook.","example":true}}},"BillingNotificationEventDto":{"type":"object","properties":{"id":{"type":"string","description":"Event ID.","example":"e8f4c2a1-3b7d-4e9f-8a1c-6b5d3e2a9f01"},"kind":{"type":"string","description":"Notification kind.","enum":["low_balance","high_usage","auto_topup"],"example":"low_balance"},"identifier":{"type":"string","description":"Tier name (`warning` / `critical` / `depleted`) for low_balance and high_usage, or outcome (`succeeded` / `failed`) for auto_topup.","example":"warning"},"accountId":{"type":"string","description":"Account the event belongs to.","example":"acc_01H8XYZ..."},"workspaceId":{"type":"string","description":"Workspace the event was scoped to, or null for account-level events.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","nullable":true},"dedupKey":{"type":"string","description":"Dedup key used to enforce one-fire-per-threshold-per-period.","example":"low_balance:warning:acc_01H8XYZ:2026-04-22"},"firedAt":{"type":"string","description":"When the event fired.","example":"2026-04-22T08:12:34.567Z","format":"date-time"},"payload":{"type":"object","description":"Kind-specific payload (threshold cents, period info, auto-topup details, etc.).","additionalProperties":true,"example":{"tierCents":100000,"balanceCents":85000}},"emailSent":{"type":"boolean","description":"Whether an email was dispatched.","example":true},"webhookSent":{"type":"boolean","description":"Whether a webhook was dispatched.","example":true}},"required":["id","kind","identifier","accountId","dedupKey","firedAt","payload","emailSent","webhookSent"]},"BillingNotificationWorkspaceOverrideDto":{"type":"object","properties":{"id":{"type":"string","description":"Override row ID.","example":"f2b5e0b8-1a3c-4f7e-9d2a-7c6b8a1d4e52"},"workspaceId":{"type":"string","description":"Workspace ID this override applies to.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"createdAt":{"type":"string","description":"Row creation timestamp.","example":"2026-04-15T12:34:56.789Z","format":"date-time"},"updatedAt":{"type":"string","description":"Row last-update timestamp.","example":"2026-04-22T08:12:34.567Z","format":"date-time"},"highUsageEnabled":{"type":"boolean","description":"Override for master high-usage toggle. Null means \"inherit\".","example":true,"nullable":true},"highUsageEmailEnabled":{"type":"boolean","description":"Override for email routing. Null means \"inherit\".","example":true,"nullable":true},"highUsageWebhookEnabled":{"type":"boolean","description":"Override for webhook routing. Null means \"inherit\".","example":true,"nullable":true},"highUsagePeriodMinutes":{"type":"number","description":"Override for rolling window minutes. Null means \"inherit\".","example":720,"nullable":true},"highUsageTiers":{"description":"Override for tier thresholds. Null means \"inherit\".","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/HighUsageTierDto"}}},"required":["id","workspaceId","createdAt","updatedAt"]},"WorkspaceBillingNotificationViewDto":{"type":"object","properties":{"accountConfig":{"description":"Fully resolved account-level config (defaults merged).","allOf":[{"$ref":"#/components/schemas/ResolvedBillingNotificationConfigDto"}]},"workspaceOverride":{"description":"Raw workspace-override row, or null if the workspace inherits everything.","nullable":true,"allOf":[{"$ref":"#/components/schemas/BillingNotificationWorkspaceOverrideDto"}]}},"required":["accountConfig"]},"UpdateWorkspaceHighUsageOverrideDto":{"type":"object","properties":{"highUsageEnabled":{"type":"boolean","description":"Override the account-level master toggle for per-workspace high-usage notifications. Undefined means \"inherit from account config\".","example":true},"highUsageEmailEnabled":{"type":"boolean","description":"Override the account-level email routing for high-usage notifications for this workspace.","example":true},"highUsageWebhookEnabled":{"type":"boolean","description":"Override the account-level webhook routing for high-usage notifications for this workspace.","example":true},"highUsagePeriodMinutes":{"type":"number","description":"Override the rolling window, in minutes, used to sum this workspace's spend when evaluating high-usage tiers. Min 5, max 43200.","example":1440,"minimum":5,"maximum":43200},"highUsageTiers":{"description":"Override the high-usage tiers for this workspace specifically. Fires when the workspace spend over the rolling window meets-or-exceeds `cents`. Tier names must be unique.","minItems":1,"maxItems":5,"type":"array","items":{"$ref":"#/components/schemas/HighUsageTierDto"}}}},"DeleteWorkspaceOverrideResponseDto":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true on success (the operation is idempotent).","example":true}},"required":["ok"]}}},"security":[{"x-api-key":[]}]}