API V2 / REFERENCE

KYB & corporate trees

Resolve the legal entity. Map the wider customer group.

Start with a confirmed legal entity, then choose the depth of data your workflow needs. Availability and permissions can vary by company, source and data section.

Identity first

The API company ID, registration number and VAT identifier are different fields. Search IDs can be strings; tree IDs can be numbers. Normalize IDs for comparison and preserve registration numbers as strings.

Find a company

POST/kyb/search

Resolve a legal entity before requesting its profile or corporate tree. Match country and registration number as well as the company name.

Parameter	Location / type	Description
`location`Required	body`string`	Required. ISO country code (GB), supported country-state code (US-CA), or a KYB location nomenclature ID.
`name`	body`string`	Company name. Supply at least one of name, registration_number, vat_number or ticker.
`registration_number`	body`string`	Company registration identifier; retain leading zeros.
`vat_number`	body`string`	VAT or EIN identifier.
`ticker`	body`string`	Stock ticker; listed among accepted identifiers in the provider validation rules.
`city_or_state`	body`array<string>`	Optional list of city or state names.
`include_provenance`	body`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

cURL request

curl --request POST "https://api.globaldatabase.com/v2/kyb/search" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "GLOBAL DATA INTELLIGENCE",
  "location": "GB"
}'

Response

200 JSON array of candidate companies. An empty array does not identify a matching entity.

View JSON example

JSON response · illustrative / abbreviated

[
  {
    "id": "29707645",
    "name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "registration_number": "09410808",
    "vat_number": "GB260423730",
    "country_code": "GB",
    "state": "Northamptonshire",
    "jurisdiction": null
  }
]

Integration notes

The search response remains an array with include_provenance=true; matching records gain source metadata. Do not assume all KYB responses use a data wrapper.

Provider reference ↗

Get a company profile

GET/kyb/{id}/lite

Read the legal identity, registration, operating status, address and available web presence for a selected company.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`include_provenance`	query`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

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/kyb/${COMPANY_ID}/lite" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 JSON company object. Example below is abbreviated, without provenance.

View JSON example

JSON response · illustrative / abbreviated

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

Integration notes

With provenance enabled, fields are organized under basic, address and contact, each with its own source where supplied. The default response is flatter.

Provider reference ↗

Get immediate group relationships

GET/kyb/{id}/group-structures/lite

Use the compact hierarchy to check the company’s immediate corporate connections before requesting a deeper tree.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`include_provenance`	query`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

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/kyb/${COMPANY_ID}/group-structures/lite" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 JSON array of tree roots by default, or an object containing data and source when provenance is enabled.

View JSON example

JSON response · illustrative / abbreviated

[
  {
    "id": 29707645,
    "name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "country": "GB",
    "registration_number": "GB 09410808",
    "selected": true,
    "children": []
  }
]

Provider reference ↗

Get the full corporate tree

GET/kyb/{id}/group-structures/full

Traverse the available parent and subsidiary relationships to map the wider account. Sister companies share a parent in the returned hierarchy.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`include_provenance`	query`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

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/kyb/${COMPANY_ID}/group-structures/full?include_provenance=true" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 JSON. This example uses include_provenance=true. Without it, the response is the array of roots.

View JSON example

JSON response · illustrative / abbreviated

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

Integration notes

Follow children recursively and use selected to locate the requested company. Preserve parent-child edges when the same entity appears more than once.
Source categories can include Modelled. A corporate relationship does not establish contract coverage, buying authority or demand. Missing relationships are not proof that none exist.

Provider reference ↗

Get financial statements

GET/kyb/{id}/financial

Retrieve available reporting periods and grouped financial measures to add scale and company context to account research.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`include_provenance`	query`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

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/kyb/${COMPANY_ID}/financial" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 JSON object with years and groups. Abbreviated example from the provider documentation.

View JSON example

JSON response · illustrative / abbreviated

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

Integration notes

Values may be strings or null. Read reporting period, currency and consolidation basis before comparing entities. Missing values are not zero.

Provider reference ↗

List company officers

GET/kyb/{id}/officers

Retrieve available officer appointments for the company. Use this for corporate context; an officer’s title alone does not establish procurement responsibility.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`page`	query`integer`	Page number.
`per_page`	query`integer`	Results requested per page. No universal maximum is documented for this endpoint.
`include_provenance`	query`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

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/kyb/${COMPANY_ID}/officers?page=1&per_page=10" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

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.

View JSON example

JSON response · illustrative / abbreviated

{
  "data": [],
  "total_pages": 0,
  "total_results": 0
}

Integration notes

Provenance can reorganize records into officer, appointment, address and optional contact sections. Read each source independently.

Provider reference ↗

List company shareholders

GET/kyb/{id}/shareholders

Retrieve available shareholding records, including holder names, share type, quantities and ownership percentages where supplied.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`page`	query`integer`	Page number.
`per_page`	query`integer`	Results requested per page. No universal maximum is documented for this endpoint.
`include_provenance`	query`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

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/kyb/${COMPANY_ID}/shareholders?page=1&per_page=10" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

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.

View JSON example

JSON response · illustrative / abbreviated

{
  "data": [],
  "total_pages": 0,
  "total_results": 0
}

Integration notes

Do not treat a null percentage as zero or infer a complete beneficial-ownership determination from an incomplete set of holdings.

Provider reference ↗

Find companies connected to an officer

POST/kyb/officers/search

Search an officer’s name and use additional filters to distinguish people with similar names. Associations require identity review.

Parameter	Location / type	Description
`name`Required	body`string`	Officer name, at least 2 characters.
`date_of_birth_year`	body`integer`	Optional four-digit birth year for disambiguation.
`country_code`	body`string`	ISO two-letter country code.
`status`	body`string`	C for current appointments; P for previous appointments.
`appointment_date`	body`object`	Optional gte / lte date bounds (YYYY-MM-DD).
`resignation_date`	body`object`	Optional gte / lte date bounds (YYYY-MM-DD).
`company_name`	body`string`	Filter by company name.
`company_reg_number`	body`string`	Filter by company registration number.
`company_status`	body`array`	Company Status nomenclature IDs, not status labels.
`company_countries`	body`array`	KYB Countries nomenclature IDs, not ISO codes.
`include_provenance`	body`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

cURL request

curl --request POST "https://api.globaldatabase.com/v2/kyb/officers/search" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Alex Morgan",
  "country_code": "GB",
  "status": "C"
}'

Response

200 JSON array of officer-to-company matches. Alex Morgan is a placeholder name; the empty response is illustrative.

View JSON example

JSON response · illustrative / abbreviated

[]

Provider reference ↗

Find companies connected to a shareholder

POST/kyb/shareholders/search/{view_mode}

Search a person or corporate holder and retrieve the companies associated with that holding. Lite and full views have separate permissions.

Parameter	Location / type	Description
`view_mode`Required	path`string`	lite returns holder/company context; full adds holding details.
`name`Required	body`string`	Holder name, 2–500 characters.
`company_name`	body`string`	Filter by company name.
`registration_number`	body`string`	Filter by company registration number.
`vat_number`	body`string`	Filter by company VAT identifier.
`location_countries`	body`array<string>`	ISO two-letter country codes, such as GB.
`percentage`	body`object`	Optional integer gte / lte bounds, each from 1 to 100.
`page`	body`integer`	Page number; default 1.
`per_page`	body`integer`	Results per page; default 10, maximum 50.
`include_provenance`	body`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

cURL request

curl --request POST "https://api.globaldatabase.com/v2/kyb/shareholders/search/lite" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example Holdings",
  "location_countries": [
    "GB"
  ],
  "page": 1,
  "per_page": 10
}'

Response

200 paginated JSON: data, total_pages and total_results. Example Holdings and the empty response are illustrative.

View JSON example

JSON response · illustrative / abbreviated

{
  "data": [],
  "total_pages": 0,
  "total_results": 0
}

Provider reference ↗

Get a combined KYB report

GET/kyb/{id}/full

Request company identity, officers, shareholders, group structure and financials together. Each section has its own entitlement and usage checks.

Parameter	Location / type	Description
`id`Required	path`integer`	Company ID returned by KYB search. This is not the company registration number.
`include_provenance`	query`boolean`	Optional source metadata. This can change the response structure; see the provenance examples.

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/kyb/${COMPANY_ID}/full" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 may contain partial failures. Sections are lite, officers, shareholders, group_structures_full and financial. Illustrative partial response below.

View JSON example

JSON response · illustrative / abbreviated

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

Integration notes

Check 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.
Officers and shareholders in this combined report are not paginated. Standalone list endpoints are paginated.

Provider reference ↗

Read provenance without losing context

Turning on include_provenance is more than adding one optional field. Search stays an array, a lite profile gains grouped sections, and a corporate tree becomes a data plus source object.

Corporate tree

Keep the relationship source alongside the nodes. A Modelled relationship should remain identifiable in your UI and exports.

Profile and financials

Preserve the source for each section. Contact enrichment and registry identity can have different origins.

Use the full KYB report only when you need several data categories. Inspect every section’s error even when HTTP status is 200.

Location nomenclature reference ↗

Download OpenAPI 3.1 Back to overview

CONTINUEWatch companies

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