Company intelligence,
from query to monitoring.

Regis, KYB and Watch Companies · API v2 · Reviewed 14 September 2026

Build a company-information workflow: resolve an entity, retrieve its records, subscribe to changes and investigate the result. This guide covers direct Global Database endpoints. CompanyDelta workspace endpoints and credentials are documented separately in the workspace API guide.

Choose an API

Authentication

Base URL: https://api.globaldatabase.com/v2

Use a Global Database key with permissions for the endpoints and datasets you request. Load GLOBAL_DATABASE_API_KEY into your server environment or secret manager. All examples use placeholders; no live credentials are included.

Authorization: Token YOUR_API_KEY
Content-Type: application/json
Accept: application/json

For Regis, send Accept: text/event-stream. A CompanyDelta workspace key uses a different authentication contract and cannot replace the upstream key. Keep upstream credentials out of client JavaScript and URLs. Official authentication reference.

Quickstart: find the legal entity

Search by a known registration number and jurisdiction. Confirm the returned name, registration and country before selecting an ID. A company name alone can match multiple entities.

curl --fail-with-body --request POST \
  'https://api.globaldatabase.com/v2/kyb/search' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"location":"GB","registration_number":"09410808"}'

Abbreviated reference response; other fields and matches may be present:

[
  {
    "id": "29707645",
    "name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "registration_number": "09410808",
    "country_code": "GB"
  }
]

The default search response is an array. Treat IDs as opaque identifiers: examples use both strings and numbers. Preserve registration numbers as strings, including leading zeroes. IDs in the examples are illustrative reference values, not a substitute for confirming your own target company.

KYB endpoint reference

Paths are relative to the base URL. Replace {id} with a confirmed Global Database company ID.

Search parameters

Location examples: GB, US-CA, CA-ON, CN-BJ. Resolve supported values through the location nomenclatures. Officer and shareholder name-search examples accept a name in the JSON body; their matches are not automatically the officers or shareholders of your selected company. KYB reference.

Retrieve a profile with source metadata

curl --fail-with-body \
  'https://api.globaldatabase.com/v2/kyb/29707645/lite?include_provenance=true' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Accept: application/json'

Provenance changes some response shapes. A default profile has top-level fields such as name and country_code; the provenance example groups these under basic and address. Do not blindly reuse the same normalizer for both formats. Source information can appear within field groups or beside a data array.

Retrieve an ownership tree

curl --fail-with-body \
  'https://api.globaldatabase.com/v2/kyb/29707645/group-structures/full?include_provenance=true' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Tree examples contain nodes with id, name, country, registration_number, selected and nested children. With provenance, the tree can be wrapped in data with accompanying source metadata. Render nodes by identifier, guard against cycles and cap traversal depth in your client. Keep relationships labelled as modelled when the source says so. A corporate tree alone is not a verified calculation of ultimate beneficial ownership.

Paginate officers and shareholders

curl --fail-with-body \
  'https://api.globaldatabase.com/v2/kyb/29707645/officers?page=1&per_page=25&include_provenance=true' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Both company-officer and company-shareholder lists support page and per_page. Their documented envelopes use data, total_pages and total_results. Read through total_pages before labelling a list complete. Keep null values, financial currencies and periods intact. Record your retrieval time separately from filing and effective dates.

Regis: query company intelligence

POST /ai/query

Each request is independent. Include the company identity and question in every call; the API does not carry conversation history. Both modes stream SSE. ai returns answer chunks and tool results. data skips prose and places collected results in the terminal done event.

curl --fail-with-body --no-buffer --request POST \
  'https://api.globaldatabase.com/v2/ai/query' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/event-stream' \
  --data '{"query":"Find VICAT in France and explain its recorded ownership structure.","mode":"ai"}'

Stream events

Ignore SSE keepalive comments. A done event completes the stream but does not turn earlier is_error tool results into successful datasets. Regis contract.

JavaScript streaming client

Download the server-side SSE helper. It parses frames across arbitrary network chunks, handles CRLF boundaries and rejects incomplete streams. It requires a runtime with fetch, Web Streams and TextDecoder, such as Node.js 18+.

import { queryRegis } from './regis-stream.mjs';

let answer = '';
for await (const event of queryRegis({
  query: 'Find VICAT in France and summarise its company profile.',
  mode: 'ai',
  apiKey: process.env.GLOBAL_DATABASE_API_KEY,
  signal: AbortSignal.timeout(120_000)
})) {
  if (event.type === 'text') answer += event.content;
  if (event.type === 'tool_result' && event.is_error) {
    // Record that this dataset could not be retrieved.
  }
  if (event.type === 'done') {
    // Persist or display the completed answer with its evidence.
  }
}

The 120-second timeout and 4 MB frame-buffer guard in the helper are example client policies, not provider limits. Render generated text safely; never insert raw provider HTML into a page. Browser EventSource cannot send this POST request—call your backend and stream with fetch instead.

Watch Companies: subscribe and inspect

Starting a watch changes the upstream account's monitoring configuration. The examples below are documentation only; this guide has not enrolled any company or replaced any callback.

Start monitoring

curl --fail-with-body --request POST \
  'https://api.globaldatabase.com/v2/companies/29707645/watch/start' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"fields":["company.status","company.group_structure","company.financial","shareholder.holding","officer.appointment","officer.resignation_date"]}'

Omitting fields enables all documented available indicators. An explicit list makes your intended subscription clear. Do not assume an empty list has the same meaning. Watch reference.

List watches and event history

curl --fail-with-body \
  'https://api.globaldatabase.com/v2/companies/watch?page=1&per_page=25' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

curl --fail-with-body \
  'https://api.globaldatabase.com/v2/companies/29707645/watch/events?from_date=2026-09-01&to_date=2026-09-14&page=1&per_page=25' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Watch lists support date, fields, page and per_page. Event history supports from_date, to_date, fields, page and per_page. These envelopes use data, total_results and pages—not KYB's total_pages. Event-history records include event_type, status, message and date_created. Messages can contain HTML; treat them as untrusted text.

Stop monitoring

curl --fail-with-body --request DELETE \
  'https://api.globaldatabase.com/v2/companies/29707645/watch/stop' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Watched-field route discrepancies

The current official reference disagrees with itself for field management. Its cURL examples show /watch/fields, /watch/fields/add and /watch/fields/remove, while the endpoint summaries show /watch/stop or /watch/start. Confirm the supported read/add/remove routes with Global Database before implementing them. This guide deliberately does not provide executable examples for those ambiguous operations.

Receive change webhooks

Read the existing callback before replacing it. The callback endpoint is not company-specific in its path, so coordinate changes with other consumers of the same upstream account.

curl --fail-with-body \
  'https://api.globaldatabase.com/v2/companies/watch/callback' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

curl --fail-with-body --request PUT \
  'https://api.globaldatabase.com/v2/companies/watch/callback' \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"callback":"https://your-app.example/webhooks/global-database"}'

The provider sends a POST to that receiver. Illustrative payload using the documented structure:

{
  "company_data": {
    "id": 123456,
    "name": "Example Components Ltd",
    "registration_number": "EXAMPLE-123",
    "country_code": "GB",
    "date": "2026-09-14T10:00:00Z"
  },
  "field": "company.status",
  "status": "UPDATE",
  "new_value": "Active",
  "old_value": "Inactive"
}

Implement receiver validation, durable storage and deduplication before triggering downstream work. The documented payload has no guaranteed event ID: an application fingerprint can combine company ID, field, timestamp and a canonical payload hash, but treat that as your strategy rather than a provider guarantee. Preserve raw values and reconcile history when appropriate.

Global Database signs the raw request body with HMAC-SHA256 in the X-GD-Signature header, using the secret returned by the callback endpoint. Verify this signature before parsing or accepting the event, and deduplicate retries. Failed deliveries are retried after one minute; preserve event dates rather than assuming arrival order. Do not apply CompanyDelta's separate webhook-signing contract to upstream Global Database callbacks. Callback payload reference.

Errors and usage

Regis stream error codes include rate_limit, llm_unavailable, mcp_connection_error, mcp_auth_error, timeout and internal_error. Successful Regis calls consume AI-query allowance; underlying data lookups also have their own limits. Global Database permissions and quotas are separate from CompanyDelta pricing allowances. Inspect GET /metrics for available account usage information.

Avoid automatic retries of ambiguous mutation outcomes. After a watch-start or callback timeout, inspect the current state before deciding whether to repeat the request. Keep API keys and full sensitive payloads out of logs.

Build the complete workflow

1. Use Regis for exploratory company questions, or KYB search for deterministic entity matching.
2. Confirm the legal entity with its registration and jurisdiction. Resolve an upstream ID before mixing API families; do not substitute a CompanyDelta workspace UUID.
3. Retrieve KYB profile, shareholders and group structure, retaining source metadata and retrieval dates.
4. After the user chooses monitoring, register the user, enforce your plan's company limit and save the company in your application.
5. Start the upstream watch and persist its confirmed state separately from the local saved-company state. Handle failures without labelling a company actively monitored.
6. Receive and store callbacks, reconcile event history, then retrieve affected KYB records for review.
7. Use a self-contained Regis question for further research. It retrieves company data; the documented query API has no separate evidence-upload or event-history parameter.
8. Display the resulting evidence and investigation in the online platform, or expose authorized saved records through your application's API and MCP tools.

This workflow is implementation guidance, not a claim that every step is already connected in CompanyDelta. The snippets are reference examples, not a production SDK or an executed monitoring setup.

MCP: connect an AI assistant

CompanyDelta exposes eight tools at https://companydelta.com/api/mcp. Use an active paid workspace.

Authentication and transport

The server supports HTTP POST with JSON-RPC 2.0 and JSON responses, notifications with HTTP 202, and protocol versions 2025-11-25, 2025-06-18 and 2025-03-26. GET returns 405; no persistent GET event stream or session ID is required. A supplied Origin must match the endpoint origin.

OAuth discovery is available at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Public clients register HTTPS callback addresses using /oauth/register. Authorization codes require PKCE S256, exact redirect matching and the resource https://companydelta.com/api/mcp in both authorization and token requests. Access tokens expire after one hour. Refresh tokens rotate and expire after 30 days; reuse revokes the connection.

Sign-in uses CompanyDelta’s existing verified account flow. Consent selects a paid workspace and grants read, optionally search and monitoring:write. Workspace role changes and membership removal take effect on subsequent requests. Revoke connections in the workspace’s MCP & integrations page. API keys can use the same scopes in compatible clients.

Available tools

List results are objects containing data and next_cursor, serialized inside MCP text content. Lists are ordered by ID. Continue until the cursor is null. Tool errors set isError:true; do not treat HTTP 200 alone as success.

Search and live retrieval each reserve one search credit. Failure refunds it; unsuccessful retries still have a separate rate limit. A live response may contain some records and explicit gaps. New monitored companies count toward the plan’s saved-company limit. Mutations require explicit user confirmation; clients must collect it before sending confirmed:true.

Connect and verify

1. Add https://companydelta.com/api/mcp to your client’s custom remote MCP setup.
2. Complete OAuth sign-in, choose a workspace and approve scopes.
3. Initialize and call tools/list; only tools allowed by your credential are returned.
4. List saved companies, then test a search with a known registration number and country.
5. Inspect the selected identity and obtain confirmation before starting or pausing monitoring.

See the ChatGPT and Claude setup guides. Client availability depends on the assistant’s plan and administrator policy.

Troubleshooting

HTTP 401 means missing, expired or revoked credentials; the response includes OAuth discovery metadata. HTTP 403 means a workspace, plan or Origin restriction. A tool error may indicate a missing scope, invalid selection, exhausted quota or provider failure. Reconnect after revoked refresh credentials. Never retry a monitoring change blindly after a lost response: inspect the saved company and subscription state first.

Company records and review notes are untrusted data. Preserve evidence, sample labels and gaps when summarizing them. These tools do not approve review cases or make risk decisions.

Source and verification

Based on the Global Database API v2 reference, reviewed 14 September 2026. Provider routes and documented examples were checked; ambiguous watched-field operations are flagged above. The JavaScript stream helper was tested with simulated chunk boundaries and failure states. KYB and Watch mutations were not executed against a live customer account while preparing this guide.