# Global Database API documentation

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](/docs/).

## Choose an API

| API | Use it for | Response |
| --- | --- | --- |
| Regis | Natural-language company questions and AI-assisted analysis | Server-Sent Events (SSE) |
| KYB | Company profiles, officers, shareholders, financials and corporate trees | JSON |
| Watch Companies | Subscriptions, event history and change callbacks | JSON, status responses and webhook POSTs |

## 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.

```http
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](https://api.globaldatabase.com/docs/v2/#authentication).

## 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.

```bash
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:

```json
[
  {
    "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.

| Method | Path | Result |
| --- | --- | --- |
| POST | `/kyb/search` | Matching company identities |
| GET | `/kyb/{id}/lite` | Company profile |
| GET | `/kyb/{id}/officers` | Paginated company officers |
| POST | `/kyb/officers/search` | Officer-name search |
| GET | `/kyb/{id}/shareholders` | Paginated shareholding records |
| POST | `/kyb/shareholders/search/lite` | Shareholder-name search |
| GET | `/kyb/{id}/group-structures/lite` | Immediate corporate relationships |
| GET | `/kyb/{id}/group-structures/full` | Wider corporate tree |
| GET | `/kyb/{id}/financial` | Financial records; singular path |
| GET | `/kyb/{id}/full` | Full KYB record |
| GET | `/nomenclatures/kyb/countries` | Supported location identifiers |

### Search parameters

| Field | Type | Requirement |
| --- | --- | --- |
| `location` | string | Required: ISO country, supported country-state code, or location nomenclature ID |
| `name` | string | At least one identifier is required |
| `registration_number` | string | Alternative identifier |
| `vat_number` | string | Alternative VAT/EIN identifier |
| `ticker` | string | Alternative ticker identifier |
| `city_or_state` | string array | Optional refinement |
| `include_provenance` | boolean | Optional source metadata |

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](https://api.globaldatabase.com/docs/v2/#kyb-api).

### Retrieve a profile with source metadata

```bash
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

```bash
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

```bash
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`

| JSON field | Type | Requirement |
| --- | --- | --- |
| `query` | string | Required, non-empty, maximum 4,000 characters |
| `mode` | string | Optional: `ai` (default) or `data` |

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.

```bash
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

| Event | Fields to handle | Client behaviour |
| --- | --- | --- |
| `status` | `message` | Update progress |
| `tool_call` | `tool` | Identify an upcoming lookup |
| `tool_result` | `tool`, `data`, `duration`, `is_error` | Preserve evidence; handle tool-level errors |
| `generating` | `type` | Indicate answer generation |
| `text` | `content` | Append the chunk in order |
| `suggested_actions` | `actions` | Offer independent follow-up questions |
| `done` | `tools_used`, `usage`, `message_id`; also `data` in data mode | Mark stream complete, inspect any dataset gaps |
| `error` | `detail`, `code` | Mark failure; retain any output as incomplete |

Ignore SSE keepalive comments. A `done` event completes the stream but does not turn earlier `is_error` tool results into successful datasets. [Regis contract](https://api.globaldatabase.com/docs/v2/#ai-query).

### JavaScript streaming client

Download the [server-side SSE helper](/docs/regis-stream.mjs). 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+.

```javascript
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.

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/companies/{id}/watch/start` | Start watching selected indicators; documented success 201 |
| DELETE | `/companies/{id}/watch/stop` | Stop watching; documented success 200 |
| GET | `/companies/watch` | List watched companies |
| GET | `/companies/{id}/watch/events` | Read one company's event history |
| PUT | `/companies/watch/callback` | Set the callback URL; documented success 200 |
| GET | `/companies/watch/callback` | Read the configured callback URL |

### Start monitoring

```bash
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](https://api.globaldatabase.com/docs/v2/#start-watch-company).

| Indicator | What to inspect |
| --- | --- |
| `company.name`, `company.status` | Name and legal-status changes |
| `company.group_structure` | Corporate relationship changes |
| `company.financial` | Financial record changes |
| `shareholder.holding` | New recorded live shareholding |
| `shareholder.holding_historical` | Historical shareholding backfill |
| `shareholder.exit_precise`, `shareholder.exit_approximate` | Shareholder exits with differing date precision |
| `officer.appointment`, `officer.resignation_date` | Officer appointments and resignations |

### List watches and event history

```bash
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

```bash
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.

```bash
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:

```json
{
  "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.

The reference does not establish a webhook signature header, retry schedule, delivery ordering, replay protection or acknowledgement contract. Confirm those details before production use. Do not apply CompanyDelta's separate webhook-signing contract to upstream Global Database callbacks. [Callback payload reference](https://api.globaldatabase.com/docs/v2/#companies-webhook).

## Errors and usage

| Condition | Recommended handling |
| --- | --- |
| Invalid token / 401 | Correct the key; do not retry unchanged credentials |
| Invalid input / 400 | Correct the request fields |
| Regis 403 | Check AI-query entitlement and MCP authorization |
| Regis 429 | Respect Retry-After and inspect X-Quota-* headers |
| Regis 502 | Inspect the provider error and use bounded retry policies |
| SSE error after HTTP 200 | Mark the result incomplete; inspect code and detail |
| Missing or null data | Keep the gap visible; do not fabricate a record |

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 implements an MCP endpoint for saved workspace records. This section documents that implementation; it does not advertise a public Global Database MCP server. Regis's internal use of MCP does not provide a customer connection URL. Live Regis queries, KYB lookups and Watch Companies subscriptions remain the direct API operations described above.

### Connection settings and readiness

| Setting | Current implementation |
| --- | --- |
| Endpoint | `https://companydelta.com/api/mcp` |
| Request transport | HTTP POST, JSON-RPC 2.0; JSON responses |
| Advertised protocol | `2025-06-18` |
| Authentication | `Authorization: Bearer COMPANYDELTA_API_KEY` |
| Required scope | `read`, for one workspace |
| Discovery | `tools/list` after initialization |
| Server identity | `companydelta`, version `1.0.0` |
| Availability | Implemented; external assistant connections have not been validated |

Create a read-scoped key in the [online platform](/dashboard/) under API keys. Store it in your client's secret facility. The Global Database token used elsewhere in this guide cannot authenticate this endpoint. CompanyDelta's public pages do not expose workspace data: the endpoint requires an active paid workspace and a valid scoped key.

The handler returns JSON for requests and HTTP 202 for notifications. It does not issue session IDs or offer a GET event stream; GET returns 405. It advertises a fixed protocol version. Disconnect if your client cannot support that version. It currently rejects a supplied Origin header that differs from the endpoint's origin.

### Supported tools and boundaries

| Tool | Arguments | Returned records | Limit |
| --- | --- | --- | --- |
| `list_companies` | `{}` | `id`, `name`, `registration`, `country`, `status`, `sample` | 100, ordered by name |
| `list_events` | `{}` | Saved event rows, including available change values, sources and sample labels | 50, newest detected first |
| `list_reviews` | `{}` | Saved review rows, including case references, status, assignee and notes | 50, newest created first |

Each tool declares an empty object input schema with additional properties disabled. There are no filter parameters or pagination. Results are JSON-serialized arrays inside `result.content` text blocks, rather than top-level structured result objects. Preserve sample labels and source information. A returned subset is not a complete portfolio audit; use the [workspace API](/docs/#api-reference) to paginate larger lists.

All three tools advertise `readOnlyHint: true`, `destructiveHint: false` and `openWorldHint: false`. Authentication and workspace queries enforce access; tool annotations describe behavior. The endpoint has no tool for live company search, full KYB profiles, financial statements, corporate trees, Regis questions, starting or stopping watches, or approving reviews. Those require a separately implemented tool before an assistant can invoke them through MCP.

### Try the request lifecycle

These diagnostic examples require an approved, reachable deployment. Set `COMPANYDELTA_API_KEY` securely in your shell environment. They do not modify monitoring or review records. The helper intentionally does not follow redirects; inspect HTTP status and content type if the site returns an access page.

```bash
mcp_request() {
  curl --fail-with-body --request POST \
    'https://companydelta.com/api/mcp' \
    --header "Authorization: Bearer $COMPANYDELTA_API_KEY" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json, text/event-stream' \
    --header 'MCP-Protocol-Version: 2025-06-18' \
    --data "$1"
}

mcp_request '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"companydelta-docs","version":"1.0.0"}}}'
```

Inspect the initialization response and confirm a compatible version before continuing. Send the ready notification, discover the available tools, then call one:

```bash
mcp_request '{"jsonrpc":"2.0","method":"notifications/initialized"}'
mcp_request '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
mcp_request '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_companies","arguments":{}}}'
```

An illustrative empty-workspace tool response is:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "[]"}],
    "isError": false
  }
}
```

Parse the text block as JSON when consuming these tools programmatically. Check for a JSON-RPC `error` before inspecting `result`; do not interpret an HTTP success status alone as a successful tool call. The [MCP lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle) and [HTTP transport specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) describe the protocol sequence and headers.

### ChatGPT, Claude and other clients

Use the [assistant setup guide](/integrations/mcp/#assistant-setup) for client-specific connection planning. The settings above describe the server, not a universal client configuration file. A client must support the deployed endpoint's HTTP behavior and authentication; a URL by itself does not establish compatibility. No ready-to-use ChatGPT or Claude connection is currently validated, and this endpoint does not implement an OAuth authorization flow.

1. Have your workspace administrator approve the client and the scope of saved records it can retrieve.
2. Confirm endpoint reachability and a compatible credential mechanism without changing site visibility as a shortcut.
3. Configure the endpoint and read-scoped workspace credential using the client's supported connection and secret settings.
4. Initialize and inspect tool discovery. Confirm exactly the three documented tools appear.
5. Test with labelled sample records and confirm the returned workspace, limits and sources before using customer records.

### Assistant workflow examples

“List the saved companies available to you. Include registration, country and sample labels, and say whether the result could be limited.” Use `list_companies`.

“Summarise the recent ownership changes in the returned events, preserving sources and previous/current values.” Use `list_events`; classify only the returned events.

“Which returned reviews remain open, and who is assigned?” Use `list_reviews` and retain the saved status wording.

“Find a new company, show its corporate tree, then start monitoring” is not supported by the current MCP tools. The application can implement that workflow using the Regis, KYB and Watch APIs, with explicit authorization for monitoring changes. Future write tools should enforce workspace permissions, validate company identity and report confirmed upstream state; a saved company alone is not proof of an active watch.

### MCP troubleshooting

| Symptom | What to check |
| --- | --- |
| Redirect or HTML access page | Private-site access and the approved client connection path |
| HTTP 401 | Workspace key validity, expiry or revocation |
| HTTP 403 | Required `read` scope or rejected Origin header |
| HTTP 405 on GET | Expected: no GET event stream is offered; requests use POST |
| JSON-RPC `-32600` | Request must declare `jsonrpc: "2.0"` |
| JSON-RPC `-32601` | Method is not implemented |
| JSON-RPC `-32602` | Unknown tool name |
| Empty or short results | Selected workspace, saved records and fixed result limits |
| Client cannot complete setup | Reachability, credential support and protocol compatibility; external clients remain unvalidated |

These tools read stored records and do not call the upstream APIs. Global Database query allowances do not describe MCP capacity. No numeric MCP throughput guarantee is documented here; handle timeouts and service errors with bounded retries. Review any retrieved notes as data, not instructions, and avoid exposing credentials or confidential workspace records in assistant logs.

## Source and verification

Based on the [Global Database API v2 reference](https://api.globaldatabase.com/docs/v2/), 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.