API V2 / REFERENCE

Watch companies

Keep a focused account plan connected to company changes.

Watch selected legal entities for supported changes. A new relationship, status change or shift in company scale can trigger a fresh account review; it does not by itself confirm an upsell opportunity.

One subscription per company

Resolve a group with KYB, choose the relevant company IDs, then enroll each company. Revisit the corporate tree when relationships change so newly discovered members can be evaluated and enrolled.

Start watching a company

POST/companies/{id}/watch/start

Enroll one company and select the changes your application needs to follow.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`fields`	body`array<string>`	Explicit list of indicators to follow. Use the field names in the monitoring field catalog.

Set COMPANY_ID in your server environment after confirming the company returned by KYB search.

cURL request

# Set COMPANY_ID to the ID you selected from KYB search.
curl --request POST "https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/start" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "fields": [
    "company.group_structure",
    "company.status",
    "company.name",
    "company.employees_number"
  ]
}'

Response

201 success. The provider does not document a JSON response schema for this operation.

Integration notes

Omitting fields enables all available indicators. Pass an explicit list to keep your monitoring scope focused.
Enrolling a parent does not automatically enroll its subsidiaries. Track the required company IDs and enroll each one.

Provider reference ↗

List watched companies

GET/companies/watch

Read the company subscriptions configured on the API account.

Parameter	Location / type	Description
`date`	query`string`	Optional date filter (YYYY-MM-DD).
`fields`	query`array<string>`	Optional field filter. The provider reference does not specify array serialization. These examples omit it; confirm the wire format before using it.
`page`	query`integer`	Page number.
`per_page`	query`integer`	Results requested per page. No universal maximum is documented for this endpoint.

cURL request

curl --request GET "https://api.globaldatabase.com/v2/companies/watch?page=1&per_page=10" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 paginated JSON with data, pages and total_results. Illustrative subscription, not a live enrollment.

View JSON example

JSON response · illustrative / abbreviated

{
  "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
}

Provider reference ↗

Read company change events

GET/companies/{id}/watch/events

Pull the company’s available event history for a bounded date range.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`from_date`	query`string`	Start date (YYYY-MM-DD).
`to_date`	query`string`	End date (YYYY-MM-DD).
`fields`	query`array<string>`	Optional field filter. The provider reference does not specify array serialization. These examples omit it; confirm the wire format before using it.
`page`	query`integer`	Page number.
`per_page`	query`integer`	Results requested per page. No universal maximum is documented for this endpoint.

Set COMPANY_ID in your server environment after confirming the company returned by KYB search.

cURL request

# Set COMPANY_ID to the ID you selected from KYB search.
curl --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" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 paginated JSON with data, pages and total_results. Illustrative event below.

View JSON example

JSON response · illustrative / abbreviated

{
  "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
}

Integration notes

Use your own date window; the fixed dates in this example are illustrative. Read all pages, and retain a checkpoint only after successful processing.
Messages 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.

Provider reference ↗

Read watched fields

GET/companies/{id}/watch/fields

Inspect the indicators currently enrolled for one company before changing its subscription.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.

Set COMPANY_ID in your server environment after confirming the company returned by KYB search.

cURL request

# Set COMPANY_ID to the ID you selected from KYB search.
curl --request GET "https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 JSON array of field names. Illustrative field selection.

View JSON example

JSON response · illustrative / abbreviated

[
  "company.group_structure",
  "company.status",
  "company.name",
  "company.employees_number"
]

Integration notes

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

Provider reference ↗

Add watched fields

PUT/companies/{id}/watch/fields/add

Extend a company’s current field selection.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`fields`	body`array<string>`	Explicit list of indicators to follow. Use the field names in the monitoring field catalog.

Set COMPANY_ID in your server environment after confirming the company returned by KYB search.

cURL request

# Set COMPANY_ID to the ID you selected from KYB search.
curl --request PUT "https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields/add" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "fields": [
    "company.financial"
  ]
}'

Response

200 JSON array of watched fields. Illustrative updated selection.

View JSON example

JSON response · illustrative / abbreviated

[
  "company.group_structure",
  "company.status",
  "company.name",
  "company.employees_number",
  "company.financial"
]

Integration notes

Always supply the intended fields. The provider marks the body field optional but does not explain omission behavior for this operation.
This 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.

Provider reference ↗

Remove watched fields

PUT/companies/{id}/watch/fields/remove

Remove selected indicators from the company subscription.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`fields`	body`array<string>`	Explicit list of indicators to follow. Use the field names in the monitoring field catalog.

Set COMPANY_ID in your server environment after confirming the company returned by KYB search.

cURL request

# Set COMPANY_ID to the ID you selected from KYB search.
curl --request PUT "https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/fields/remove" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "fields": [
    "company.financial"
  ]
}'

Response

200 JSON array of remaining watched fields. Illustrative updated selection.

View JSON example

JSON response · illustrative / abbreviated

[
  "company.group_structure",
  "company.status",
  "company.name",
  "company.employees_number"
]

Integration notes

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

Provider reference ↗

Stop watching a company

DELETE/companies/{id}/watch/stop

Remove the company’s upstream monitoring subscription.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.

Set COMPANY_ID in your server environment after confirming the company returned by KYB search.

cURL request

# Set COMPANY_ID to the ID you selected from KYB search.
curl --request DELETE "https://api.globaldatabase.com/v2/companies/${COMPANY_ID}/watch/stop" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 success. The provider does not document a JSON response schema for this operation.

Integration notes

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

Provider reference ↗

Supported watch indicators

For expansion research, start with company.group_structure, company.status, company.name and company.employees_number. Add other indicators only when your workflow uses them.

Company15 indicators

Locations6 indicators

Shareholders6 indicators

Employees4 indicators

employee.appointment
employee.phone
employee.email
employee.resignation_date

Officers4 indicators

officer.appointment
officer.phone
officer.email
officer.resignation_date

Provider reference discrepancies

Field-management cURL paths differ from their endpoint labels. Older examples also use names such as vat_number that do not match the current indicator catalog. This guide documents the cURL paths and current catalog; verify accepted field names during integration.

Download OpenAPI 3.1 Back to overview

CONTINUEWebhook notifications

Based on the Global Database API v2 reference ↗ · Reviewed 14 September 2026. Examples are illustrative or abbreviated, not live company reports.