{ "openapi": "3.1.0", "info": { "title": "EntityReach integration guide — Global Database APIs", "version": "2026-09-14", "description": "EntityReach-maintained reference for Regis AI, KYB and Watch Companies. Calls use the Global Database API, not an EntityReach API proxy. Examples are abbreviated or illustrative. Product entitlements and quotas are provisioned separately. Source discrepancies are called out per operation. Optional watch fields query-array serialization is not specified by the provider and is omitted from machine-executable parameters pending confirmation." }, "servers": [ { "url": "https://api.globaldatabase.com/v2" } ], "externalDocs": { "description": "Official provider reference", "url": "https://api.globaldatabase.com/docs/v2/" }, "security": [ { "ApiKey": [] } ], "tags": [ { "name": "regis", "description": "AI research over a Server-Sent Events response" }, { "name": "kyb", "description": "Company identity and corporate relationships" }, { "name": "monitoring", "description": "Per-company subscriptions and event history" }, { "name": "webhooks", "description": "Account callback configuration" } ], "paths": { "/ai/query": { "post": { "operationId": "ai_query", "tags": [ "regis" ], "summary": "Ask Regis", "description": "Send a self-contained research question. Regis selects company-data tools and streams their results, with an optional written answer.\n\nEach successful request uses one AI-query request. Underlying data-tool usage is metered separately.\n\nFor follow-ups, include only the relevant prior context in a new query and keep the complete string within 4,000 characters.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#ai-query" }, "parameters": [], "responses": { "200": { "description": "200 text/event-stream. Read frames incrementally until done or error; do not call response.json().", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE frames terminated by a blank line. A done event completes the request; error signals failure after streaming starts." } } } }, "400": { "description": "Invalid query or missing account API key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Missing entitlement or mcp_auth_error.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate or quota limit; inspect Retry-After and X-Quota-* headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "mcp_connection_error.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl --no-buffer --request POST \"https://api.globaldatabase.com/v2/ai/query\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: text/event-stream' \\\n --data '{\n \"query\": \"Find GLOBAL DATA INTELLIGENCE in GB and show its corporate group. Separate company facts from possible expansion questions.\",\n \"mode\": \"ai\"\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst response = await fetch(`https://api.globaldatabase.com/v2/ai/query`, {\n method: 'POST',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json',\n Accept: 'text/event-stream'\n },\n body: JSON.stringify({\n \"query\": \"Find GLOBAL DATA INTELLIGENCE in GB and show its corporate group. Separate company facts from possible expansion questions.\",\n \"mode\": \"ai\"\n}),\n signal: AbortSignal.timeout(120000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\n// Use the complete streaming client linked below to parse SSE.\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\ntry {\n while (true) {\n const { value, done } = await reader.read();\n if (done) break;\n process.stdout.write(decoder.decode(value, { stream: true }));\n }\n process.stdout.write(decoder.decode());\n} finally {\n reader.releaseLock();\n}" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\npayload = json.loads(\"{\\\"query\\\":\\\"Find GLOBAL DATA INTELLIGENCE in GB and show its corporate group. Separate company facts from possible expansion questions.\\\",\\\"mode\\\":\\\"ai\\\"}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/ai/query\",\n method='POST',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json',\n 'Accept': 'text/event-stream'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=120) as response:\n # Prints the raw SSE stream. Parse complete frames before using data.\n for line in response:\n print(line.decode('utf-8'), end='', flush=True)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 4000, "description": "One self-contained question; maximum 4,000 characters. No conversation history is stored by this endpoint." }, "mode": { "type": "string", "enum": [ "ai", "data" ], "default": "ai", "description": "ai streams prose and tool results; data returns tool results without prose. Default: ai." } }, "additionalProperties": true, "required": [ "query" ] }, "example": { "query": "Find GLOBAL DATA INTELLIGENCE in GB and show its corporate group. Separate company facts from possible expansion questions.", "mode": "ai" } } } } } }, "/kyb/search": { "post": { "operationId": "company_search", "tags": [ "kyb" ], "summary": "Find a company", "description": "Resolve a legal entity before requesting its profile or corporate tree. Match country and registration number as well as the company name.\n\nThe search response remains an array with include_provenance=true; matching records gain source metadata. Do not assume all KYB responses use a data wrapper.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#search-kyb" }, "parameters": [], "responses": { "200": { "description": "200 JSON array of candidate companies. An empty array does not identify a matching entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchResults" }, "example": [ { "id": "29707645", "name": "GLOBAL DATA INTELLIGENCE LIMITED", "registration_number": "09410808", "vat_number": "GB260423730", "country_code": "GB", "state": "Northamptonshire", "jurisdiction": null } ] } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl --request POST \"https://api.globaldatabase.com/v2/kyb/search\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"GLOBAL DATA INTELLIGENCE\",\n \"location\": \"GB\"\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/search`, {\n method: 'POST',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"name\": \"GLOBAL DATA INTELLIGENCE\",\n \"location\": \"GB\"\n}),\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\npayload = json.loads(\"{\\\"name\\\":\\\"GLOBAL DATA INTELLIGENCE\\\",\\\"location\\\":\\\"GB\\\"}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/search\",\n method='POST',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string", "description": "Required. ISO country code (GB), supported country-state code (US-CA), or a KYB location nomenclature ID." }, "name": { "type": "string", "description": "Company name. Supply at least one of name, registration_number, vat_number or ticker." }, "registration_number": { "type": "string", "description": "Company registration identifier; retain leading zeros." }, "vat_number": { "type": "string", "description": "VAT or EIN identifier." }, "ticker": { "type": "string", "description": "Stock ticker; listed among accepted identifiers in the provider validation rules." }, "city_or_state": { "type": "array", "items": { "type": "string" }, "description": "Optional list of city or state names." }, "include_provenance": { "type": "boolean", "description": "Optional source metadata. This can change the response structure; see the provenance examples." } }, "additionalProperties": true, "required": [ "location" ], "anyOf": [ { "required": [ "name" ] }, { "required": [ "registration_number" ] }, { "required": [ "vat_number" ] }, { "required": [ "ticker" ] } ] }, "example": { "name": "GLOBAL DATA INTELLIGENCE", "location": "GB" } } } } } }, "/kyb/{id}/lite": { "get": { "operationId": "company_profile", "tags": [ "kyb" ], "summary": "Get a company profile", "description": "Read the legal identity, registration, operating status, address and available web presence for a selected company.\n\nWith provenance enabled, fields are organized under basic, address and contact, each with its own source where supplied. The default response is flatter.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#lite-kyb" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "include_provenance", "in": "query", "required": false, "description": "Optional source metadata. This can change the response structure; see the provenance examples.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "200 JSON company object. Example below is abbreviated, without provenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProfile" }, "example": { "id": "29707645", "name": "GLOBAL DATA INTELLIGENCE LIMITED", "registration_number": "09410808", "vat_number": "GB260423730", "incorporation_date": "2015-01-28", "status": "Active", "country_code": "GB", "country_name": "United Kingdom", "legal_form": "Private limited company (Ltd.)", "website": "https://www.globaldatabase.com/", "ticker": null } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/lite\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/lite`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/{COMPANY_ID}/lite\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/kyb/{id}/group-structures/lite": { "get": { "operationId": "group_lite", "tags": [ "kyb" ], "summary": "Get immediate group relationships", "description": "Use the compact hierarchy to check the company’s immediate corporate connections before requesting a deeper tree.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#group-structures-lite-kyb" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "include_provenance", "in": "query", "required": false, "description": "Optional source metadata. This can change the response structure; see the provenance examples.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "200 JSON array of tree roots by default, or an object containing data and source when provenance is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" }, "example": [ { "id": 29707645, "name": "GLOBAL DATA INTELLIGENCE LIMITED", "country": "GB", "registration_number": "GB 09410808", "selected": true, "children": [] } ] } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/group-structures/lite\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/group-structures/lite`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/{COMPANY_ID}/group-structures/lite\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/kyb/{id}/group-structures/full": { "get": { "operationId": "group_full", "tags": [ "kyb" ], "summary": "Get the full corporate tree", "description": "Traverse the available parent and subsidiary relationships to map the wider account. Sister companies share a parent in the returned hierarchy.\n\nFollow children recursively and use selected to locate the requested company. Preserve parent-child edges when the same entity appears more than once.\n\nSource categories can include Modelled. A corporate relationship does not establish contract coverage, buying authority or demand. Missing relationships are not proof that none exist.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#group-structures-full-kyb" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "include_provenance", "in": "query", "required": false, "description": "Optional source metadata. This can change the response structure; see the provenance examples.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "200 JSON. This example uses include_provenance=true. Without it, the response is the array of roots.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" }, "example": { "data": [ { "id": 29707645, "name": "GLOBAL DATA INTELLIGENCE LIMITED", "country": "GB", "registration_number": "GB 09410808", "selected": true, "children": [ { "id": 222828368, "name": "GLOBAL DATABASE, SRL", "country": "MD", "registration_number": "MD 1021600025805", "selected": false, "children": [] } ] } ], "source": { "category": "Modelled", "id": 895, "name": "Global Data Intelligence Limited", "url": "https://www.globaldatabase.com/" } } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/group-structures/full?include_provenance=true\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/group-structures/full?include_provenance=true`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/{COMPANY_ID}/group-structures/full?include_provenance=true\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/kyb/{id}/financial": { "get": { "operationId": "company_financials", "tags": [ "kyb" ], "summary": "Get financial statements", "description": "Retrieve available reporting periods and grouped financial measures to add scale and company context to account research.\n\nValues may be strings or null. Read reporting period, currency and consolidation basis before comparing entities. Missing values are not zero.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#financial-kyb" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "include_provenance", "in": "query", "required": false, "description": "Optional source metadata. This can change the response structure; see the provenance examples.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "200 JSON object with years and groups. Abbreviated example from the provider documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Financials" }, "example": { "years": [ "2018-01-31" ], "groups": [ { "id": "Summary", "name": "Summary", "order": 0, "list": [ { "name": "Currency", "list": { "2018-01-31": "GBP" } }, { "name": "Employee Numbers", "list": { "2018-01-31": "1" } } ] } ] } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/financial\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/financial`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/{COMPANY_ID}/financial\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/kyb/{id}/officers": { "get": { "operationId": "company_officers", "tags": [ "kyb" ], "summary": "List company officers", "description": "Retrieve available officer appointments for the company. Use this for corporate context; an officer’s title alone does not establish procurement responsibility.\n\nProvenance can reorganize records into officer, appointment, address and optional contact sections. Read each source independently.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#officers-kyb" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results requested per page. No universal maximum is documented for this endpoint.", "schema": { "type": "integer" } }, { "name": "include_provenance", "in": "query", "required": false, "description": "Optional source metadata. This can change the response structure; see the provenance examples.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "200 paginated JSON: data, total_pages and total_results. Records can include id, first_name, last_name, job_title, appointed_at, resigned_at and work_status. Empty-result illustration below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybPage" }, "example": { "data": [], "total_pages": 0, "total_results": 0 } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/officers?page=1&per_page=10\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/officers?page=1&per_page=10`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/{COMPANY_ID}/officers?page=1&per_page=10\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/kyb/{id}/shareholders": { "get": { "operationId": "company_shareholders", "tags": [ "kyb" ], "summary": "List company shareholders", "description": "Retrieve available shareholding records, including holder names, share type, quantities and ownership percentages where supplied.\n\nDo not treat a null percentage as zero or infer a complete beneficial-ownership determination from an incomplete set of holdings.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#shareholders-kyb" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results requested per page. No universal maximum is documented for this endpoint.", "schema": { "type": "integer" } }, { "name": "include_provenance", "in": "query", "required": false, "description": "Optional source metadata. This can change the response structure; see the provenance examples.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "200 paginated JSON: data, total_pages and total_results. Records may include id, name, percentage, quantity, currency, share_price and share_type. Empty-result illustration below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybPage" }, "example": { "data": [], "total_pages": 0, "total_results": 0 } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/shareholders?page=1&per_page=10\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/shareholders?page=1&per_page=10`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/{COMPANY_ID}/shareholders?page=1&per_page=10\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/kyb/officers/search": { "post": { "operationId": "officer_search", "tags": [ "kyb" ], "summary": "Find companies connected to an officer", "description": "Search an officer’s name and use additional filters to distinguish people with similar names. Associations require identity review.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#officers-search-kyb" }, "parameters": [], "responses": { "200": { "description": "200 JSON array of officer-to-company matches. Alex Morgan is a placeholder name; the empty response is illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordArray" }, "example": [] } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl --request POST \"https://api.globaldatabase.com/v2/kyb/officers/search\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Alex Morgan\",\n \"country_code\": \"GB\",\n \"status\": \"C\"\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/officers/search`, {\n method: 'POST',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"name\": \"Alex Morgan\",\n \"country_code\": \"GB\",\n \"status\": \"C\"\n}),\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\npayload = json.loads(\"{\\\"name\\\":\\\"Alex Morgan\\\",\\\"country_code\\\":\\\"GB\\\",\\\"status\\\":\\\"C\\\"}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/officers/search\",\n method='POST',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "description": "Officer name, at least 2 characters." }, "date_of_birth_year": { "type": "integer", "description": "Optional four-digit birth year for disambiguation." }, "country_code": { "type": "string", "description": "ISO two-letter country code." }, "status": { "type": "string", "enum": [ "C", "P" ], "description": "C for current appointments; P for previous appointments." }, "appointment_date": { "type": "object", "properties": { "gte": { "type": "string", "format": "date" }, "lte": { "type": "string", "format": "date" } }, "description": "Optional gte / lte date bounds (YYYY-MM-DD)." }, "resignation_date": { "type": "object", "properties": { "gte": { "type": "string", "format": "date" }, "lte": { "type": "string", "format": "date" } }, "description": "Optional gte / lte date bounds (YYYY-MM-DD)." }, "company_name": { "type": "string", "description": "Filter by company name." }, "company_reg_number": { "type": "string", "description": "Filter by company registration number." }, "company_status": { "type": "array", "items": {}, "description": "Company Status nomenclature IDs, not status labels." }, "company_countries": { "type": "array", "items": {}, "description": "KYB Countries nomenclature IDs, not ISO codes." }, "include_provenance": { "type": "boolean", "description": "Optional source metadata. This can change the response structure; see the provenance examples." } }, "additionalProperties": true, "required": [ "name" ] }, "example": { "name": "Alex Morgan", "country_code": "GB", "status": "C" } } } } } }, "/kyb/shareholders/search/{view_mode}": { "post": { "operationId": "shareholder_search", "tags": [ "kyb" ], "summary": "Find companies connected to a shareholder", "description": "Search a person or corporate holder and retrieve the companies associated with that holding. Lite and full views have separate permissions.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#shareholders-search-kyb" }, "parameters": [ { "name": "view_mode", "in": "path", "required": true, "description": "lite returns holder/company context; full adds holding details.", "schema": { "type": "string", "enum": [ "lite", "full" ] } } ], "responses": { "200": { "description": "200 paginated JSON: data, total_pages and total_results. Example Holdings and the empty response are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybPage" }, "example": { "data": [], "total_pages": 0, "total_results": 0 } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl --request POST \"https://api.globaldatabase.com/v2/kyb/shareholders/search/lite\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Example Holdings\",\n \"location_countries\": [\n \"GB\"\n ],\n \"page\": 1,\n \"per_page\": 10\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/shareholders/search/lite`, {\n method: 'POST',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"name\": \"Example Holdings\",\n \"location_countries\": [\n \"GB\"\n ],\n \"page\": 1,\n \"per_page\": 10\n}),\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\npayload = json.loads(\"{\\\"name\\\":\\\"Example Holdings\\\",\\\"location_countries\\\":[\\\"GB\\\"],\\\"page\\\":1,\\\"per_page\\\":10}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/shareholders/search/lite\",\n method='POST',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 500, "description": "Holder name, 2–500 characters." }, "company_name": { "type": "string", "description": "Filter by company name." }, "registration_number": { "type": "string", "description": "Filter by company registration number." }, "vat_number": { "type": "string", "description": "Filter by company VAT identifier." }, "location_countries": { "type": "array", "items": { "type": "string" }, "description": "ISO two-letter country codes, such as GB." }, "percentage": { "type": "object", "properties": { "gte": { "type": "integer", "minimum": 1, "maximum": 100 }, "lte": { "type": "integer", "minimum": 1, "maximum": 100 } }, "description": "Optional integer gte / lte bounds, each from 1 to 100." }, "page": { "type": "integer", "default": 1, "description": "Page number; default 1." }, "per_page": { "type": "integer", "default": 10, "maximum": 50, "description": "Results per page; default 10, maximum 50." }, "include_provenance": { "type": "boolean", "description": "Optional source metadata. This can change the response structure; see the provenance examples." } }, "additionalProperties": true, "required": [ "name" ] }, "example": { "name": "Example Holdings", "location_countries": [ "GB" ], "page": 1, "per_page": 10 } } } } } }, "/kyb/{id}/full": { "get": { "operationId": "full_kyb", "tags": [ "kyb" ], "summary": "Get a combined KYB report", "description": "Request company identity, officers, shareholders, group structure and financials together. Each section has its own entitlement and usage checks.\n\nCheck section.error before using each section. A 403 within a section means access or usage was blocked; a 404 means that section had no data.\n\nOfficers and shareholders in this combined report are not paginated. Standalone list endpoints are paginated.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#full-kyb" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "include_provenance", "in": "query", "required": false, "description": "Optional source metadata. This can change the response structure; see the provenance examples.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "200 may contain partial failures. Sections are lite, officers, shareholders, group_structures_full and financial. Illustrative partial response below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullKyb" }, "example": { "lite": { "error": { "status_code": 403, "detail": { "message_guard": "API entitlement or usage limit prevented this section." } } }, "officers": [], "shareholders": [], "group_structures_full": [], "financial": { "error": { "status_code": 404, "detail": "No financial data available in this illustrative response." } } } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/full\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/kyb/${COMPANY_ID}/full`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/kyb/{COMPANY_ID}/full\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/companies/{id}/watch/start": { "post": { "operationId": "watch_start", "tags": [ "monitoring" ], "summary": "Start watching a company", "description": "Enroll one company and select the changes your application needs to follow.\n\nOmitting fields enables all available indicators. Pass an explicit list to keep your monitoring scope focused.\n\nEnrolling a parent does not automatically enroll its subsidiaries. Track the required company IDs and enroll each one.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#start-watch-company" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "201 success. The provider does not document a JSON response schema for this operation." }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request POST \"https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/start\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"fields\": [\n \"company.group_structure\",\n \"company.status\",\n \"company.name\",\n \"company.employees_number\"\n ]\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/start`, {\n method: 'POST',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"fields\": [\n \"company.group_structure\",\n \"company.status\",\n \"company.name\",\n \"company.employees_number\"\n ]\n}),\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\npayload = json.loads(\"{\\\"fields\\\":[\\\"company.group_structure\\\",\\\"company.status\\\",\\\"company.name\\\",\\\"company.employees_number\\\"]}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/{COMPANY_ID}/watch/start\",\n method='POST',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" }, "description": "Explicit list of indicators to follow. Use the field names in the monitoring field catalog." } }, "additionalProperties": true }, "example": { "fields": [ "company.group_structure", "company.status", "company.name", "company.employees_number" ] } } } } } }, "/companies/watch": { "get": { "operationId": "watch_list", "tags": [ "monitoring" ], "summary": "List watched companies", "description": "Read the company subscriptions configured on the API account.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#watched-companies" }, "parameters": [ { "name": "date", "in": "query", "required": false, "description": "Optional date filter (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results requested per page. No universal maximum is documented for this endpoint.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "200 paginated JSON with data, pages and total_results. Illustrative subscription, not a live enrollment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchPage" }, "example": { "data": [ { "id": "29707645", "name": "GLOBAL DATA INTELLIGENCE LIMITED", "country_code": "GB", "registration_number": "09410808", "date": "2026-09-14", "fields": [ "company.group_structure", "company.status", "company.name", "company.employees_number" ] } ], "total_results": 1, "pages": 1 } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl --request GET \"https://api.globaldatabase.com/v2/companies/watch?page=1&per_page=10\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/watch?page=1&per_page=10`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/watch?page=1&per_page=10\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "x-unresolved-query-parameters": [ { "name": "fields", "in": "query", "type": "array", "description": "Optional field filter. The provider reference does not specify array serialization. These examples omit it; confirm the wire format before using it.", "required": false } ] } }, "/companies/{id}/watch/events": { "get": { "operationId": "watch_events", "tags": [ "monitoring" ], "summary": "Read company change events", "description": "Pull the company’s available event history for a bounded date range.\n\nUse your own date window; the fixed dates in this example are illustrative. Read all pages, and retain a checkpoint only after successful processing.\n\nMessages may contain HTML. Render as text or sanitize. Event history does not document a stable event ID or the same old/new fields as webhooks.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#all-companies-events" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } }, { "name": "from_date", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "End date (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results requested per page. No universal maximum is documented for this endpoint.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "200 paginated JSON with data, pages and total_results. Illustrative event below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsPage" }, "example": { "data": [ { "status": "UPDATED", "message": "Illustrative employee-count change; verify the current company data.", "date_created": "2026-09-14T09:30:00Z", "event_type": "company.employees_number" } ], "total_results": 1, "pages": 1 } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/events?from_date=2026-09-01&to_date=2026-09-14&page=1&per_page=10\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/events?from_date=2026-09-01&to_date=2026-09-14&page=1&per_page=10`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/{COMPANY_ID}/watch/events?from_date=2026-09-01&to_date=2026-09-14&page=1&per_page=10\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "x-unresolved-query-parameters": [ { "name": "fields", "in": "query", "type": "array", "description": "Optional field filter. The provider reference does not specify array serialization. These examples omit it; confirm the wire format before using it.", "required": false } ] } }, "/companies/{id}/watch/fields": { "get": { "operationId": "watch_fields", "tags": [ "monitoring" ], "summary": "Read watched fields", "description": "Inspect the indicators currently enrolled for one company before changing its subscription.\n\nThe provider’s cURL example uses /watch/fields; its endpoint label incorrectly shows /watch/stop. This guide follows the cURL example and the existing EntityReach integration.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#watched-company-fields" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "200 JSON array of field names. Illustrative field selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringArray" }, "example": [ "company.group_structure", "company.status", "company.name", "company.employees_number" ] } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request GET \"https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/{COMPANY_ID}/watch/fields\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/companies/{id}/watch/fields/add": { "put": { "operationId": "watch_fields_add", "tags": [ "monitoring" ], "summary": "Add watched fields", "description": "Extend a company’s current field selection.\n\nAlways supply the intended fields. The provider marks the body field optional but does not explain omission behavior for this operation.\n\nThis path follows the provider’s cURL example; its endpoint label incorrectly shows /watch/start. Legacy field examples also differ from the current field catalog. Confirm accepted field names for your account.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#add-watched-fields" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "200 JSON array of watched fields. Illustrative updated selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringArray" }, "example": [ "company.group_structure", "company.status", "company.name", "company.employees_number", "company.financial" ] } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request PUT \"https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields/add\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"fields\": [\n \"company.financial\"\n ]\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields/add`, {\n method: 'PUT',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"fields\": [\n \"company.financial\"\n ]\n}),\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\npayload = json.loads(\"{\\\"fields\\\":[\\\"company.financial\\\"]}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/{COMPANY_ID}/watch/fields/add\",\n method='PUT',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" }, "description": "Explicit list of indicators to follow. Use the field names in the monitoring field catalog." } }, "additionalProperties": true }, "example": { "fields": [ "company.financial" ] } } } } } }, "/companies/{id}/watch/fields/remove": { "put": { "operationId": "watch_fields_remove", "tags": [ "monitoring" ], "summary": "Remove watched fields", "description": "Remove selected indicators from the company subscription.\n\nSupply an explicit field list. This path follows the provider’s cURL example; the endpoint label incorrectly shows /watch/start. Confirm field identifiers and behavior before changing shared account subscriptions.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#remove-watched-fields" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "200 JSON array of remaining watched fields. Illustrative updated selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringArray" }, "example": [ "company.group_structure", "company.status", "company.name", "company.employees_number" ] } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request PUT \"https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields/remove\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"fields\": [\n \"company.financial\"\n ]\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields/remove`, {\n method: 'PUT',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"fields\": [\n \"company.financial\"\n ]\n}),\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\npayload = json.loads(\"{\\\"fields\\\":[\\\"company.financial\\\"]}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/{COMPANY_ID}/watch/fields/remove\",\n method='PUT',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" }, "description": "Explicit list of indicators to follow. Use the field names in the monitoring field catalog." } }, "additionalProperties": true }, "example": { "fields": [ "company.financial" ] } } } } } }, "/companies/{id}/watch/stop": { "delete": { "operationId": "watch_stop", "tags": [ "monitoring" ], "summary": "Stop watching a company", "description": "Remove the company’s upstream monitoring subscription.\n\nThis changes the provider account’s subscription. If several workspaces share a key, keep a company usage count and stop watching only when no workspace still needs it.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#stop-watch-company" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID returned by KYB search. This is not the company registration number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "200 success. The provider does not document a JSON response schema for this operation." }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "# Set COMPANY_ID to the ID you selected from KYB search.\ncurl --request DELETE \"https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/stop\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst COMPANY_ID = process.env.COMPANY_ID;\nif (!COMPANY_ID || !/^\\d+$/.test(COMPANY_ID)) {\n throw new Error('Set COMPANY_ID from a confirmed KYB match');\n}\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/stop`, {\n method: 'DELETE',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nCOMPANY_ID = os.environ['COMPANY_ID']\nif not COMPANY_ID.isdecimal():\n raise ValueError('Use a confirmed numeric KYB company ID')\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/{COMPANY_ID}/watch/stop\",\n method='DELETE',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] } }, "/companies/watch/callback": { "get": { "operationId": "callback_read", "tags": [ "webhooks" ], "summary": "Read the callback URL", "description": "Inspect the account’s current company-notification destination before updating it.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#get-callback-url" }, "parameters": [], "responses": { "200": { "description": "200 JSON object with callback. The destination in this example is a placeholder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Callback" }, "example": { "callback": "https://your-app.example/webhooks/company-changes" } } } }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl --request GET \"https://api.globaldatabase.com/v2/companies/watch/callback\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\"" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/watch/callback`, {\n method: 'GET',\n headers: {\n Authorization: `Token ${key}`\n },\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/watch/callback\",\n method='GET',\n headers={\n 'Authorization': f'Token {key}'\n }\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ] }, "put": { "operationId": "callback_set", "tags": [ "webhooks" ], "summary": "Set the callback URL", "description": "Configure where the provider sends company change notifications.\n\nThis is an account-level callback setting, not a per-company URL. Coordinate changes when the API account is shared.", "externalDocs": { "url": "https://api.globaldatabase.com/docs/v2/#set-callback-url" }, "parameters": [], "responses": { "200": { "description": "200 success. The provider does not document a JSON response schema for this operation." }, "default": { "description": "Provider HTTP error; response shapes differ by endpoint. Check status and safe diagnostics." } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl --request PUT \"https://api.globaldatabase.com/v2/companies/watch/callback\" \\\n --header \"Authorization: Token $GLOBAL_DATABASE_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"callback\": \"https://your-app.example/webhooks/company-changes\"\n}'" }, { "lang": "JavaScript", "source": "// Server-side JavaScript (Node.js 20+).\nconst key = process.env.GLOBAL_DATABASE_API_KEY;\nif (!key) throw new Error('Set GLOBAL_DATABASE_API_KEY');\nconst response = await fetch(`https://api.globaldatabase.com/v2/companies/watch/callback`, {\n method: 'PUT',\n headers: {\n Authorization: `Token ${key}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"callback\": \"https://your-app.example/webhooks/company-changes\"\n}),\n signal: AbortSignal.timeout(60000)\n});\nif (!response.ok) {\n throw new Error(`API request failed: ${response.status}`);\n}\nconst text = await response.text();\nconsole.log(text ? JSON.parse(text) : null);" }, { "lang": "Python", "source": "# Python 3; standard library only. Run on your server.\nimport json\nimport os\nimport urllib.request\n\nkey = os.environ['GLOBAL_DATABASE_API_KEY']\npayload = json.loads(\"{\\\"callback\\\":\\\"https://your-app.example/webhooks/company-changes\\\"}\")\nrequest = urllib.request.Request(\n f\"https://api.globaldatabase.com/v2/companies/watch/callback\",\n method='PUT',\n headers={\n 'Authorization': f'Token {key}',\n 'Content-Type': 'application/json'\n },\n data=json.dumps(payload).encode('utf-8')\n)\nwith urllib.request.urlopen(request, timeout=60) as response:\n raw = response.read()\n print(json.loads(raw) if raw else None)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "string", "format": "uri", "description": "Your HTTPS receiver URL. Replace the example with a deployed endpoint you control." } }, "additionalProperties": true, "required": [ "callback" ] }, "example": { "callback": "https://your-app.example/webhooks/company-changes" } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Send the complete value: Token YOUR_API_KEY. This is not Bearer authentication." } }, "schemas": { "Source": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer" } ] }, "category": { "type": "string" }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "comment": { "type": "string" } }, "additionalProperties": true }, "SectionError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "properties": { "status_code": { "type": "integer" }, "detail": {} }, "additionalProperties": true } }, "additionalProperties": true }, "CompanySearchResults": { "type": "array", "items": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer" } ] }, "name": { "type": "string" }, "registration_number": { "type": "string" }, "vat_number": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/Source" } }, "additionalProperties": true } }, "CompanyProfile": { "description": "Default profile is flat. With provenance, fields are grouped under basic, address and contact.", "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer" } ] }, "name": { "type": "string" }, "registration_number": { "type": "string" }, "vat_number": { "type": [ "string", "null" ] }, "incorporation_date": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "basic": { "type": "object", "additionalProperties": true }, "address": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "GroupNode": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer" } ] }, "name": { "type": "string" }, "country": { "type": "string" }, "registration_number": { "type": "string" }, "selected": { "type": "boolean" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/GroupNode" } } }, "additionalProperties": true }, "GroupResponse": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/GroupNode" } }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupNode" } }, "source": { "$ref": "#/components/schemas/Source" } }, "required": [ "data" ], "additionalProperties": true } ], "example": { "data": [ { "id": 29707645, "name": "GLOBAL DATA INTELLIGENCE LIMITED", "country": "GB", "registration_number": "GB 09410808", "selected": true, "children": [ { "id": 222828368, "name": "GLOBAL DATABASE, SRL", "country": "MD", "registration_number": "MD 1021600025805", "selected": false, "children": [] } ] } ], "source": { "category": "Modelled", "id": 895, "name": "Global Data Intelligence Limited", "url": "https://www.globaldatabase.com/" } } }, "Financials": { "type": "object", "properties": { "years": { "type": "array", "items": { "type": "string" } }, "groups": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "source": { "$ref": "#/components/schemas/Source" } }, "additionalProperties": true }, "KybPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total_pages": { "type": "integer" }, "total_results": { "type": "integer" }, "source": { "$ref": "#/components/schemas/Source" } }, "additionalProperties": true }, "RecordArray": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "StringArray": { "type": "array", "items": { "type": "string" } }, "WatchPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer" } ] }, "name": { "type": "string" }, "country_code": { "type": "string" }, "registration_number": { "type": "string" }, "date": { "type": "string", "format": "date" }, "fields": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "pages": { "type": "integer" }, "total_results": { "type": "integer" } }, "additionalProperties": true }, "EventsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string", "description": "Can contain HTML. Render as text or sanitize." }, "date_created": { "type": "string", "format": "date-time" }, "event_type": { "type": "string" } }, "additionalProperties": true } }, "pages": { "type": "integer" }, "total_results": { "type": "integer" } }, "additionalProperties": true }, "Callback": { "type": "object", "properties": { "callback": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "FullKyb": { "type": "object", "properties": { "lite": { "anyOf": [ { "$ref": "#/components/schemas/CompanyProfile" }, { "$ref": "#/components/schemas/SectionError" } ] }, "officers": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "$ref": "#/components/schemas/SectionError" } ] }, "shareholders": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "$ref": "#/components/schemas/SectionError" } ] }, "group_structures_full": { "anyOf": [ { "$ref": "#/components/schemas/GroupResponse" }, { "$ref": "#/components/schemas/SectionError" } ] }, "financial": { "anyOf": [ { "$ref": "#/components/schemas/Financials" }, { "$ref": "#/components/schemas/SectionError" } ] } } }, "CompanyChangeNotification": { "type": "object", "properties": { "company_data": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer" } ] }, "name": { "type": "string" }, "registration_number": { "type": "string" }, "country_code": { "type": "string" }, "date": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "field": { "type": "string" }, "status": { "type": "string" }, "old_value": {}, "new_value": {} }, "additionalProperties": true, "example": { "company_data": { "id": 29707645, "name": "GLOBAL DATA INTELLIGENCE LIMITED", "registration_number": "09410808", "country_code": "GB", "date": "2026-09-14T09:30:00Z" }, "field": "company.employees_number", "status": "UPDATE", "new_value": "120", "old_value": "100" } } } }, "webhooks": { "companyChange": { "post": { "summary": "Company change notification to your configured receiver", "description": "Incoming notification payload. Sender verification, retries and ordering are not specified in the provider reference; agree these arrangements before production use. No receiver authentication scheme is asserted by this payload-only definition.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyChangeNotification" } } } }, "responses": { "default": { "description": "Receiver response contract is not specified by the provider documentation." } } } } }, "x-watch-field-catalog": { "Company": [ "company.name", "company.status", "company.registration_number", "company.vat", "company.address_street", "company.email", "company.phone", "company.fax", "company.website", "company.bank", "company.employees_number", "company.trading_activity_export", "company.trading_activity_import", "company.group_structure", "company.financial" ], "Locations": [ "office.identity", "office.email", "office.fax", "office.phone", "office.website", "address.street" ], "Shareholders": [ "shareholder.holding", "shareholder.holding_historical", "shareholder.exit_precise", "shareholder.exit_approximate", "shareholder.share_type", "shareholder.share_price" ], "Employees": [ "employee.appointment", "employee.phone", "employee.email", "employee.resignation_date" ], "Officers": [ "officer.appointment", "officer.phone", "officer.email", "officer.resignation_date" ] } }