Zephira developer platform · production

Registry-sourced KYB data through one Zephira API.

Search companies and retrieve legal identity, officers, shareholders, corporate structures, and filed financials. The ten documented operations are backed by Zephira's configured company-data service and preserve every successful response field.

Make the first request Download OpenAPI JSON

Base URLhttps://dashboard.zephira.ai/api/v1Live

10KYB operations

3permission scopes

1 unitper successful call

0 unitsfor failed calls

Authentication & quickstart

Use the key from your Zephira dashboard.

Generate a production key under API keys, grant only the permissions your workload needs, and keep the secret in a server-side environment variable. The key works immediately: free workspaces share three successful requests per UTC day across API calls and dashboard profile unlocks, while paid workspaces use their plan allowance.

AuthorizationAuthorization: Bearer zph_live_…Never expose the key in browser code, mobile apps, logs, or source control.

company:readownership:readfinancials:read

cURLCompany search

curl --request POST 'https://dashboard.zephira.ai/api/v1/kyb/search' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Global Data Intelligence","location":"GB","include_provenance":true}'

Free-trial quota headers: inspect X-Quota-Daily-Limit, X-Quota-Daily-Remaining, and X-Quota-Daily-Reset on each authenticated response. The fourth successful request returns 429 ALLOWANCE_EXHAUSTED.

Integration help

Use the URL and key format from this guide.

Keys created in your dashboard use Authorization: Bearer zph_live_… with the base URL https://dashboard.zephira.ai/api/v1. Set ZEPHIRA_API_KEY to your own active key before running the examples. The quoted header in each cURL example reads that environment variable.

Coming from an older example? Examples using api.zephira.ai/v2 and Authorization: Token describe a separate API. Replacing its hostname or version does not convert an example to this dashboard API. Use a complete request from this guide.

What you need	Supported request after the base URL
Find a company ID	`POST /kyb/search`
Disclosed shareholders	`GET /kyb/{id}/shareholders`
Corporate group structure	`GET /kyb/{id}/group-structures/full`

/ownership/{id} is not a supported route on this API. Choose shareholders or group structure according to the information you need; their responses are different.

A 401 means the key is missing, invalid, revoked, or sent with the wrong authentication format. A 404 with API_ROUTE_NOT_FOUND or KYB_ROUTE_NOT_FOUND means the route, method, or query parameters are unsupported. A DATA_SERVICE_404 means the data service did not find a record for the requested company ID.

Unsupported requests with a valid Bearer key appear in your usage log and consume zero units. Include the X-Zephira-Request-Id value in a support request so we can trace the failure.

Data contract

Complete fields without false certainty.

All returned fields pass through

Zephira does not discard optional or jurisdiction-specific fields from successful KYB responses.

Provenance on demand

Set include_provenance=true to receive source metadata where the module supports it.

Null stays null

A missing, null, or empty value means it was not returned. It is not converted into a negative conclusion.

Important: field availability is record- and jurisdiction-dependent. Officers, shareholders, financials, and group structures can be empty even when the company exists.

API reference

Ten production KYB operations.

POST/kyb/searchSearch companies GET/kyb/{id}/liteGet company profile GET/kyb/{id}/officersList company officers POST/kyb/officers/searchSearch officers GET/kyb/{id}/shareholdersList disclosed shareholders POST/kyb/shareholders/search/{view_mode}Search shareholders GET/kyb/{id}/group-structures/liteGet immediate group structure GET/kyb/{id}/group-structures/fullGet complete group structure GET/kyb/{id}/financialGet filed financials GET/kyb/{id}/fullGet complete KYB record

POST/kyb/search

Live

Company identity · 01

Search companies

Find the correct legal entity by name, registration number, VAT/EIN, or ticker within a jurisdiction.

Scopes company:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`location`	body	string	Required	ISO country code, US/CA/CN country-state code, or Global Database KYB location identifier.
`name`	body	string	Optional	Company name. Supply at least one search identifier.
`registration_number`	body	string	Optional	Local company registration number.
`vat_number`	body	string	Optional	VAT, tax, or EIN identifier.
`ticker`	body	string	Optional	Listed-company ticker.
`city_or_state`	body	string[]	Optional	Optional city or state names used to narrow results.
`include_provenance`	body	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

Use US-CA, CA-ON, or CN-BJ style locations where a state or province is required.
Search results are candidates; confirm the identifier before requesting a detailed record.

cURLRequest

curl --request POST 'https://dashboard.zephira.ai/api/v1/kyb/search' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Global Data Intelligence","location":"GB","include_provenance":true}'

JSONSuccess response

[
  {
    "id": 29707645,
    "name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "registration_number": "09410808",
    "vat_number": "GB260423730",
    "country_code": "GB",
    "state": "Northamptonshire",
    "jurisdiction": null,
    "source": {
      "category": "Government Registry",
      "comment": "Official registry data",
      "id": 197,
      "name": "Companies House",
      "url": "https://find-and-update.company-information.service.gov.uk"
    }
  }
]

Response field reference 8 documented field groups

Field	Type	Meaning
`id`	integer \| string	Company ID used by all company-detail endpoints.
`name`	string	Registered company name.
`registration_number`	string \| null	Local registration number; leading zeroes are preserved.
`vat_number`	string \| null	VAT, tax, or EIN identifier when available.
`country_code`	string	ISO alpha-2 country code.
`state`	string \| null	State, province, or registry region when supplied.
`jurisdiction`	string \| null	Registry jurisdiction when distinct from country or state.
`source`	source \| absent	Returned when include_provenance=true.

GET/kyb/{id}/lite

Live

Company identity · 02

Get company profile

Retrieve core legal identity, status, registered address, legal form, website, LinkedIn URL, and source evidence.

Scopes company:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`id`	path	integer	Required	Company ID returned by the search endpoint.
`include_provenance`	query	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

Without provenance, the same fields are returned in a flat object.
Null means the field was not returned for this company or jurisdiction.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v1/kyb/29707645/lite?include_provenance=true' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json'

JSONSuccess response

{
  "id": 29707645,
  "basic": {
    "name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "registration_number": "09410808",
    "vat_number": "GB260423730",
    "incorporation_date": "2015-01-28",
    "status": "Active",
    "legal_form": "Private limited company (Ltd.)",
    "source": {
      "category": "Government Registry",
      "comment": "Official registry data",
      "id": 197,
      "name": "Companies House",
      "url": "https://find-and-update.company-information.service.gov.uk"
    }
  },
  "address": {
    "country_code": "GB",
    "country_name": "United Kingdom",
    "country_region": "Northamptonshire",
    "address_street": "Artisans' House",
    "address_location": "7 Queensbridge",
    "address_city": "Northampton",
    "zip_code": "NN4 7BF",
    "jurisdiction": null,
    "source": {
      "category": "Government Registry",
      "comment": "Official registry data",
      "id": 197,
      "name": "Companies House",
      "url": "https://find-and-update.company-information.service.gov.uk"
    }
  },
  "contact": {
    "website": "https://www.globaldatabase.com/",
    "linkedin": "linkedin.com/company/global-database",
    "source": {
      "category": "Enriched",
      "comment": "Contact information enrichment",
      "id": 1153,
      "name": "Contact Enrichment",
      "url": null
    }
  }
}

Response field reference 19 documented field groups

Field	Type	Meaning
`id`	integer \| string	Company ID.
`basic.name`	string	Registered company name.
`basic.registration_number`	string \| null	Registration number.
`basic.vat_number`	string \| null	VAT, tax, or EIN identifier.
`basic.incorporation_date`	date \| null	Incorporation date in YYYY-MM-DD format.
`basic.status`	string \| null	Registry-reported company status.
`basic.legal_form`	string \| null	Registry-reported legal form.
`address.country_code`	string \| null	ISO alpha-2 country code.
`address.country_name`	string \| null	Country name.
`address.country_region`	string \| null	Region, state, or province.
`address.address_street`	string \| null	Registered-address line.
`address.address_location`	string \| null	Additional registered-address line.
`address.address_city`	string \| null	Registered-address city.
`address.zip_code`	string \| null	Postal code.
`address.jurisdiction`	string \| null	Registry jurisdiction.
`contact.website`	string \| null	Company website when available.
`contact.linkedin`	string \| null	Company LinkedIn URL when available.
`ticker / basic.ticker`	string \| null	Listed-company ticker when available.
`basic.source / address.source / contact.source`	source \| absent	Field-group provenance returned when requested.

GET/kyb/{id}/officers

Live

People & ownership · 03

List company officers

Return current and former directors, officers, appointment dates, roles, published addresses, and available enrichment.

Scopes company:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`id`	path	integer	Required	Company ID returned by the search endpoint.
`page`	query	integer	Optional	One-based page number. Default 1.
`per_page`	query	integer	Optional	Results per page from 1 to 50. Default 10.
`include_provenance`	query	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v1/kyb/29707645/officers' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json'

JSONSuccess response

{
  "data": [
    {
      "id": 212160656,
      "first_name": "Nicolae",
      "last_name": "Buldumac",
      "appointed_at": "2015-01-28",
      "resigned_at": null,
      "work_status": "ACTIVE",
      "date_of_birth_year": 1985,
      "date_of_birth_month": 12,
      "job_title": "Director",
      "address_country": "GB",
      "address_line_1": "7 Queensbridge, Artisans' House",
      "address_locality": "Northampton",
      "address_region": "Northamptonshire",
      "address_postal_code": "NN4 7BF"
    }
  ],
  "total_pages": 1,
  "total_results": 3
}

Response field reference 10 documented field groups

Field	Type	Meaning
`data[].id`	integer \| string	Officer record ID.
`data[].first_name / last_name`	string \| null	Published officer name fields.
`data[].appointed_at / resigned_at`	date \| null	Appointment and resignation dates.
`data[].work_status`	string \| null	Current or previous appointment status.
`data[].date_of_birth_year / date_of_birth_month`	integer \| null	Published partial date of birth when available.
`data[].job_title`	string \| null	Registry-reported role.
`data[].address_*`	string \| null	Published officer-address fields.
`data[].officer / appointment / address`	object \| absent	Provenance-aware field groups when requested.
`data[].contact.email / contact.phone`	string \| null \| absent	Licensed contact fields when returned with provenance.
`total_pages / total_results`	integer	Pagination totals.

POST/kyb/officers/search

Live

People & ownership · 04

Search officers

Search an individual by name and return the companies where they hold or previously held a statutory appointment.

Scopes company:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`name`	body	string	Required	Full or partial officer name; minimum two characters.
`date_of_birth_year`	body	integer	Optional	Four-digit year used for disambiguation.
`country_code`	body	string	Optional	ISO alpha-2 country code.
`status`	body	C \| P	Optional	Current or previous appointment.
`appointment_date`	body	{gte,lte}	Optional	Inclusive YYYY-MM-DD appointment-date range.
`resignation_date`	body	{gte,lte}	Optional	Inclusive YYYY-MM-DD resignation-date range.
`company_name`	body	string	Optional	Optional company-name filter.
`company_reg_number`	body	string	Optional	Optional company-registration-number filter.
`company_status`	body	array	Optional	Company-status nomenclature IDs.
`company_countries`	body	array	Optional	KYB-country nomenclature IDs.
`include_provenance`	body	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

cURLRequest

curl --request POST 'https://dashboard.zephira.ai/api/v1/kyb/officers/search' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Nicolae Buldumac","country_code":"GB"}'

JSONSuccess response

[
  {
    "id": 212160656,
    "company_id": 29707645,
    "company_name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "registration_number": "09410808",
    "company_status": "Active",
    "incorporation_date": "2015-01-28",
    "full_name": "Nicolae Buldumac",
    "first_name": "Nicolae",
    "last_name": "Buldumac",
    "middle_name": null,
    "title": "Mr",
    "sex": "M",
    "nationality": "Romanian",
    "date_of_birth_year": 1985,
    "date_of_birth_month": 12,
    "officer_role": "Director",
    "appointed_at": "2015-01-28",
    "resigned_at": null,
    "work_status": "ACTIVE",
    "country_of_residence": "GB",
    "address_country": "GB",
    "address_line_1": "7 Queensbridge, Artisans' House",
    "address_locality": "Northampton",
    "address_region": "Northamptonshire",
    "address_postal_code": "NN4 7BF",
    "email": "nbuldumac@globaldatabase.com"
  }
]

Response field reference 9 documented field groups

Field	Type	Meaning
`id`	integer \| string	Officer record ID.
`company_id / company_name / registration_number`	mixed	Connected-company identity.
`company_status / incorporation_date`	string \| date \| null	Connected-company status and incorporation date.
`full_name / first_name / middle_name / last_name / title`	string \| null	Published officer name and title.
`sex / nationality / country_of_residence`	string \| null	Published person attributes where available.
`date_of_birth_year / date_of_birth_month`	integer \| null	Published partial date of birth.
`officer_role / appointed_at / resigned_at / work_status`	mixed	Appointment details.
`address_* / email / phone`	string \| null	Published or licensed contact fields when returned.
`company / officer / appointment / address / contact`	object \| absent	Provenance-aware field groups when requested.

GET/kyb/{id}/shareholders

Live

People & ownership · 05

List disclosed shareholders

Return direct shareholder names, quantities, percentages, share classes, prices, values, and currency where disclosed.

Scopes ownership:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`id`	path	integer	Required	Company ID returned by the search endpoint.
`page`	query	integer	Optional	One-based page number. Default 1.
`per_page`	query	integer	Optional	Results per page from 1 to 50. Default 10.
`include_provenance`	query	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

A direct shareholder is not automatically an ultimate beneficial owner.
An empty response does not prove that a company has no shareholders; disclosure varies by jurisdiction.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v1/kyb/29707645/shareholders?include_provenance=true' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json'

JSONSuccess response

{
  "data": [
    {
      "currency": "GBP",
      "id": 712449329,
      "name": "NICOLAE BULDUMAC",
      "percentage": 90,
      "quantity": 9000,
      "share_price": 0.01,
      "share_type": "ORDINARY",
      "share_value": "9000.0 ORDINARY GBP 0.01",
      "status": null,
      "total_value": 90
    }
  ],
  "source": {
    "category": "Government Registry",
    "comment": "Official registry data",
    "id": 197,
    "name": "Companies House",
    "url": "https://find-and-update.company-information.service.gov.uk"
  },
  "total_pages": 1,
  "total_results": 2
}

Response field reference 12 documented field groups

Field	Type	Meaning
`data[].id`	integer \| string	Shareholding record ID.
`data[].name`	string	Published shareholder name.
`data[].percentage`	number \| null	Published direct ownership percentage.
`data[].quantity`	number \| null	Number of shares.
`data[].share_price`	number \| null	Stated price per share.
`data[].share_type`	string \| null	Share class or type.
`data[].share_value`	string \| null	Source-formatted holding description.
`data[].currency`	string \| null	Currency code.
`data[].status`	string \| null	Holding status when supplied.
`data[].total_value`	number \| null	Reported or calculated total value.
`source`	source \| absent	Response provenance when requested.
`total_pages / total_results`	integer	Pagination totals.

POST/kyb/shareholders/search/{view_mode}

Live

People & ownership · 06

Search shareholders

Find companies linked to a named individual or corporate shareholder, with lite or full shareholding detail.

Scopes ownership:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`view_mode`	path	lite \| full	Required	Lite returns holder and company; full adds holding details.
`name`	body	string	Required	Shareholder name from 2 to 500 characters.
`company_name`	body	string	Optional	Optional company-name filter.
`registration_number`	body	string	Optional	Optional company-registration-number filter.
`vat_number`	body	string	Optional	Optional company VAT-number filter.
`location_countries`	body	string[]	Optional	ISO alpha-2 country filters.
`percentage`	body	{gte,lte}	Optional	Ownership range from 1 to 100.
`page`	body	integer	Optional	One-based page number. Default 1.
`per_page`	body	integer	Optional	Results per page from 1 to 50. Default 10.
`include_provenance`	body	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

cURLRequest

curl --request POST 'https://dashboard.zephira.ai/api/v1/kyb/shareholders/search/full' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Nicolae Buldumac","location_countries":["GB"],"page":1,"per_page":10,"include_provenance":true}'

JSONSuccess response

{
  "data": [
    {
      "company": {
        "id": 29707645,
        "name": "GLOBAL DATA INTELLIGENCE LIMITED",
        "registration_number": "09410808",
        "address": {
          "zip": "NN4 7BF",
          "city": "Northampton",
          "address1": "Artisans' House",
          "address2": "7 Queensbridge",
          "country_region": "Northamptonshire"
        },
        "vat_number": "GB260423730"
      },
      "created": "2026-03-08T00:30:10,037+0000",
      "currency": "GBP",
      "id": 712449329,
      "name": "NICOLAE BULDUMAC",
      "percentage": 90,
      "quantity": 9000,
      "share_price": 0.01,
      "share_type": "ORDINARY",
      "share_value": "9000.0 ORDINARY GBP 0.01",
      "status": "C",
      "type": "Person",
      "source": {
        "category": "Government Registry",
        "comment": "Official registry data",
        "id": 197,
        "name": "Companies House",
        "url": "https://find-and-update.company-information.service.gov.uk"
      }
    }
  ],
  "total_pages": 1,
  "total_results": 1
}

Response field reference 7 documented field groups

Field	Type	Meaning
`data[].company`	object	Connected company identity, address, registration number, and VAT number.
`data[].name / type`	string \| null	Holder name and person/corporate classification.
`data[].id / created / status`	mixed	Holding identity, creation date, and status in full mode.
`data[].percentage / quantity / share_price`	number \| null	Holding economics in full mode.
`data[].share_type / share_value / currency`	string \| null	Share-class and value fields in full mode.
`data[].source`	source \| absent	Per-record provenance when requested.
`total_pages / total_results`	integer	Pagination totals.

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

Live

People & ownership · 07

Get immediate group structure

Return a simplified company hierarchy for quick parent and subsidiary checks.

Scopes ownership:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`id`	path	integer	Required	Company ID returned by the search endpoint.
`include_provenance`	query	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

Corporate linkage is relationship data, not an automatic beneficial-owner conclusion.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v1/kyb/29707645/group-structures/lite?include_provenance=true' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json'

JSONSuccess response

{
  "data": [
    {
      "id": 29707645,
      "name": "GLOBAL DATA INTELLIGENCE LIMITED",
      "country": "GB",
      "registration_number": "GB 09410808",
      "selected": true,
      "children": []
    }
  ],
  "source": {
    "category": "Modelled",
    "comment": "Relationship derived using proprietary linkage methodologies and available corporate relationship data",
    "id": 895,
    "name": "Global Data Intelligence Limited",
    "url": "https://www.globaldatabase.com/"
  }
}

Response field reference 7 documented field groups

Field	Type	Meaning
`data[].id`	integer \| string	Company ID.
`data[].name`	string \| null	Company name.
`data[].country`	string \| null	Country code.
`data[].registration_number`	string \| null	Country-qualified registration number.
`data[].selected`	boolean	Whether the node is the requested company.
`data[].children`	node[]	Immediate related company nodes.
`source`	source \| absent	Relationship-method provenance when requested.

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

Live

People & ownership · 08

Get complete group structure

Return the available multi-level parent, subsidiary, and related-company hierarchy.

Scopes ownership:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`id`	path	integer	Required	Company ID returned by the search endpoint.
`include_provenance`	query	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

Depth depends on available corporate-linkage evidence.
Do not treat a terminal corporate node as a natural-person UBO without further ownership evidence.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v1/kyb/29707645/group-structures/full?include_provenance=true' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json'

JSONSuccess response

{
  "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",
    "comment": "Relationship derived using proprietary linkage methodologies and available corporate relationship data",
    "id": 895,
    "name": "Global Data Intelligence Limited",
    "url": "https://www.globaldatabase.com/"
  }
}

Response field reference 5 documented field groups

Field	Type	Meaning
`data[].id / name`	mixed	Company identity.
`data[].country / registration_number`	string \| null	Jurisdiction and company number.
`data[].selected`	boolean	Requested-company marker.
`data[].children`	recursive node[]	Nested corporate hierarchy.
`source`	source \| absent	Relationship-method provenance when requested.

GET/kyb/{id}/financial

Live

Financials · 09

Get filed financials

Retrieve multi-year filed statements, metric groups, source values, and period-over-period progress indicators.

Scopes financials:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`id`	path	integer	Required	Company ID returned by the search endpoint.
`include_provenance`	query	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

Metric names vary by filing regime and accounting taxonomy.
Preserve decimal precision and null values; do not coerce unavailable fields to zero.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v1/kyb/29707645/financial?include_provenance=true' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json'

JSONSuccess response

{
  "years": [
    "2023-01-31",
    "2024-01-31",
    "2025-01-31"
  ],
  "groups": [
    {
      "id": "Summary",
      "name": "Summary",
      "order": 0,
      "list": [
        {
          "name": "Net Assets",
          "list": {
            "2023-01-31": "-239021.00",
            "2024-01-31": "-252504.00",
            "2025-01-31": "-213633.00"
          },
          "progress": [
            -95,
            -100,
            -85
          ]
        }
      ]
    }
  ],
  "source": {
    "category": "Government Registry",
    "comment": "Official registry data",
    "id": 197,
    "name": "Companies House",
    "url": "https://find-and-update.company-information.service.gov.uk"
  }
}

Response field reference 6 documented field groups

Field	Type	Meaning
`years`	string[]	Reporting-period dates.
`groups[].id / name / order`	mixed	Statement group identity and display order.
`groups[].list[].name`	string	Source financial metric label.
`groups[].list[].list`	object	Reporting-period to source value map. Values may be strings, numbers, or null.
`groups[].list[].progress`	number[] \| absent	Period comparison values when supplied.
`source`	source \| absent	Financial-statement provenance when requested.

GET/kyb/{id}/full

Live

Complete profile · 10

Get complete KYB record

Retrieve company identity, officers, shareholders, full group structure, and financials in one response.

Scopes company:readownership:readfinancials:readSuccessful request 1 unit

Parameters

Name	Location	Type	Requirement	Description
`id`	path	integer	Required	Company ID returned by the search endpoint.
`include_provenance`	query	boolean	Optional	Add source metadata to the response. Recommended for audit and compliance workflows.

This route requires all three read scopes.
For latency-sensitive flows, call only the modules needed for the decision.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v1/kyb/29707645/full' \
  --header "Authorization: Bearer $ZEPHIRA_API_KEY" \
  --header 'Accept: application/json'

JSONSuccess response

{
  "lite": {
    "id": 29707645,
    "name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "registration_number": "09410808",
    "vat_number": "GB260423730",
    "incorporation_date": "2015-01-28",
    "status": "Active",
    "country_code": "GB",
    "legal_form": "Private limited company (Ltd.)"
  },
  "officers": [
    {
      "id": 212160656,
      "first_name": "Nicolae",
      "last_name": "Buldumac",
      "work_status": "ACTIVE",
      "job_title": "Director"
    }
  ],
  "shareholders": [
    {
      "id": 712449329,
      "name": "NICOLAE BULDUMAC",
      "percentage": 90,
      "quantity": 9000,
      "share_type": "ORDINARY",
      "currency": "GBP"
    }
  ],
  "group_structures_full": [
    {
      "company_id": 222828368,
      "country_source": "GB",
      "country_target": "MD",
      "source": "GB 09410808",
      "target": "MD 1021600025805",
      "title": "GLOBAL DATA INTELLIGENCE LIMITED",
      "target_title": "GLOBAL DATABASE, SRL",
      "temporary": false
    }
  ],
  "financial": {
    "id": "Summary",
    "name": "Summary",
    "years": [
      "2023-01-31",
      "2024-01-31",
      "2025-01-31"
    ],
    "groups": []
  }
}

Response field reference 6 documented field groups

Field	Type	Meaning
`lite`	company profile	All company-profile fields from the lite endpoint.
`officers`	officer[]	All officer fields from the officers endpoint.
`shareholders`	shareholder[]	All direct-shareholding fields from the shareholders endpoint.
`group_structures_full`	relationship[]	Available corporate linkage records.
`financial`	financial object	All filed-financial fields from the financial endpoint.
`source objects`	source \| absent	Field-group provenance when include_provenance=true.

Common fields

Source and pagination objects.

Source object

Field	Type	Meaning
`category`	string	Evidence class, such as Government Registry, Enriched, or Modelled.
`comment`	string \| null	Source-method note supplied with the record.
`id`	integer \| string \| null	Internal source catalogue identifier.
`name`	string \| null	Registry or source name.
`url`	string \| null	Source or registry URL when available.

Pagination

datatotal_pagestotal_results

Use one-based pages. per_page accepts 1–50.

Financial values

yearsgroupslist

Metric labels and available periods follow the source filing taxonomy.

Corporate hierarchy

selectedchildrensource

Relationship depth depends on available linkage evidence.

Errors & billing

Failed requests do not consume units.

Status	Code	Meaning
400	`INVALID_REQUEST`	Invalid JSON, unsupported fields, or invalid parameter values.
401	`UNAUTHENTICATED`	Missing, invalid, revoked, or incorrectly formatted Zephira key.
403	`PRODUCTION_KEY_REQUIRED / INSUFFICIENT_SCOPE`	A live key and the required scopes are required.
404	`API_ROUTE_NOT_FOUND / KYB_ROUTE_NOT_FOUND`	Unsupported route, method, or query parameters. Follow documentation_url in the response.
404	`DATA_SERVICE_404`	The data service did not find a record for this company ID.
413	`BODY_TOO_LARGE`	JSON body exceeds 64 KB.
429	`ALLOWANCE_EXHAUSTED`	The daily free limit or paid-plan allowance has been used.
502	`DATA_SERVICE_UNAVAILABLE`	The company-data dependency failed or returned an invalid response.
503	`ACCOUNT_SERVICE_UNAVAILABLE / USAGE_LEDGER_UNAVAILABLE`	Zephira could not verify access, configuration, or record usage.
504	`DATA_SERVICE_TIMEOUT`	The dependency exceeded 25 seconds.

JSONError response

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This operation requires: ownership:read.",
    "status": 403
  },
  "request_id": "zph_req_7a0f68f28ff1494d84dc21e1766f09db"
}

Security

Production integration rules.

Keep keys server-side

Use a secrets manager and one key per workload.

Use least privilege

Grant only the scopes required by the integration.

Retain request IDs

Log X-Zephira-Request-Id for reconciliation and support.

Respect availability

Do not interpret missing shareholder or officer records as a verified absence.