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.

Create API key OpenAPI JSON

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

10KYB operations

v2API version

Tokenauthentication

JSONresponse format

Self-service setup

Your API access is ready in the dashboard.

Open Dashboard → API keys. Paid workspaces have a key prepared automatically. Choose Reveal API key, or keep using your existing key. Workspace Owners, Admins and Developers manage credentials.
Copy the key when it is shown and save it in your server's ZEPHIRA_API_KEY environment variable. For additional keys or a free workspace, choose Create API key.
Choose Run first request to see a live company response and updated credits. A successful test uses one credit; the saved result is reused on refresh. Company profile details can be added later.

Dashboard gateway base URLhttps://dashboard.zephira.ai/api/v2Send Authorization: Token followed by your dashboard-generated token.

cURLDashboard gateway · company profile

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

Your token works immediately; no support request is needed. Existing active production dashboard keys also work. Every endpoint example below uses this gateway. Permissions, revocation and your workspace allowance apply; successful requests count one unit and failed requests are not charged.

If you lose the token, generate a replacement and revoke the old one. Full tokens cannot be retrieved after their first display.

Download OpenAPI JSON

Authentication & first request

Search with your dashboard token.

Set ZEPHIRA_API_KEY to the token you generated in Dashboard → API keys. Keep it in a server-side environment variable and send it in the Authorization header with the Token prefix.

AuthorizationAuthorization: Token $ZEPHIRA_API_KEYNever expose the key in browser code, mobile apps, logs, or source control.

cURLCompany search

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

Postman and OpenAPI clients: download the specification above and enter Token YOUR_ZEPHIRA_API_KEY as the complete Authorization header value. The specification already selects the correct dashboard API URL.

Integration help

Use the URL and key format from this guide.

Use https://dashboard.zephira.ai/api/v2 with the token generated in Dashboard → API keys. The quoted header in each cURL example reads your ZEPHIRA_API_KEY environment variable. Existing integrations at api.zephira.ai have a separate direct API guide.

Postman and OpenAPI clients: add an Authorization header with the value Token YOUR_ZEPHIRA_API_KEY. When importing the OpenAPI specification, enter that complete value, including Token and one space.

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.

For a 401, check that the environment variable is set, the token is active for this API, and the header begins with Token followed by one space. For a 404, check the method, endpoint path and company ID against the examples below.

If a request still fails, send support the request method, URL, HTTP status and error response. Remove your API token before sharing an example.

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.

Authentication TokenRequired permissions company:read

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/v2/kyb/search' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions company:read

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/v2/kyb/29707645/lite?include_provenance=true' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions company:read

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/v2/kyb/29707645/officers' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions company:read

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/v2/kyb/officers/search' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions ownership:read

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/v2/kyb/29707645/shareholders?include_provenance=true' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions ownership:read

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/v2/kyb/shareholders/search/full' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions ownership:read

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/v2/kyb/29707645/group-structures/lite?include_provenance=true' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions ownership:read

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/v2/kyb/29707645/group-structures/full?include_provenance=true' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions financials:read

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/v2/kyb/29707645/financial?include_provenance=true' \
  --header "Authorization: Token $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.

Authentication TokenRequired permissions company:read, ownership:read, financials:read

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.

For latency-sensitive flows, call only the modules needed for the decision.

cURLRequest

curl --request GET 'https://dashboard.zephira.ai/api/v2/kyb/29707645/full' \
  --header "Authorization: Token $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

Check the response before retrying.

Status	What to check
400	Check the JSON body, required fields and parameter values.
401	Check that your dashboard token is active and the header begins with Token followed by one space.
403	Check your token permissions and workspace subscription status.
404	Check the endpoint path, HTTP method and company ID.
429	Check your workspace allowance, daily limits and any retry instructions in the response.
5xx	Retain the error response and retry temporary service failures with backoff.

API requests share your workspace allowance with dashboard and MCP usage. Each successful data request counts one unit; failed requests are not charged. Review Usage and Request logs in your dashboard for the request ID, charging decision and remaining allowance.

Security

Production integration rules.

Keep keys server-side

Store your token in a secrets manager or server environment.

Limit access

Share tokens only with systems and people that need API access.

Retain error details

Log the request time, status and any returned request ID. Never log the token.

Respect availability

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

Existing direct API integrations at api.zephira.ai

The direct service uses https://api.zephira.ai/v2 and a token issued separately for that service. Dashboard-generated tokens use the dashboard gateway documented above. Keep your existing direct token and URL if your integration already uses the direct service.

cURLDirect API · separately issued token

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

Download direct API OpenAPI JSON

Direct service access and billing follow your direct API agreement. For new integrations, create a dashboard API key and use the gateway setup above.