{"openapi":"3.1.0","info":{"title":"Zephira KYB API","version":"1.0.0","summary":"Zephira Data AI registry-sourced company intelligence for verification, ownership, and financial workflows.","description":"The Zephira Data AI KYB API exposes ten company-intelligence operations through Zephira-issued credentials. Free workspaces share three successful requests per UTC day across API calls and dashboard profile unlocks; paid workspaces use their plan allowance. Successful responses preserve all fields returned for the requested company and jurisdiction, including optional and jurisdiction-specific fields.","termsOfService":"https://zephira.ai/terms-and-conditions/","contact":{"name":"Zephira support","email":"support@zephira.ai","url":"https://zephira.ai/contact-us/"}},"servers":[{"url":"https://dashboard.zephira.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Company identity"},{"name":"People & ownership"},{"name":"Financials"},{"name":"Complete profile"}],"paths":{"/kyb/search":{"post":{"operationId":"searchKyb","tags":["Company identity"],"summary":"Search companies","description":"Find the correct legal entity by name, registration number, VAT/EIN, or ticker within a jurisdiction.\n\nUse US-CA, CA-ON, or CN-BJ style locations where a state or province is required.\n\nSearch results are candidates; confirm the identifier before requesting a detailed record.","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"string","pattern":"^(?:[A-Z]{2}|(?:US|CA|CN)-[A-Z0-9]{2,3}|\\d+(?:_\\d+)+)$","description":"ISO country code, US/CA/CN country-state code, or Global Database KYB location identifier."},"name":{"type":"string","minLength":1,"description":"Company name. Supply at least one search identifier."},"registration_number":{"type":"string","minLength":1,"description":"Local company registration number."},"vat_number":{"type":"string","minLength":1,"description":"VAT, tax, or EIN identifier."},"ticker":{"type":"string","minLength":1,"description":"Listed-company ticker."},"city_or_state":{"type":"array","items":{"type":"string","minLength":1},"description":"Optional city or state names used to narrow results."},"include_provenance":{"type":"boolean","description":"Add source metadata to the response. Recommended for audit and compliance workflows."}},"required":["location"],"anyOf":[{"required":["name"]},{"required":["registration_number"]},{"required":["vat_number"]},{"required":["ticker"]}],"additionalProperties":false},"example":{"name":"Global Data Intelligence","location":"GB","include_provenance":true}}}},"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":[{"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"}}]}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["company:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/{id}/lite":{"get":{"operationId":"liteKyb","tags":["Company identity"],"summary":"Get company profile","description":"Retrieve core legal identity, status, registered address, legal form, website, LinkedIn URL, and source evidence.\n\nWithout provenance, the same fields are returned in a flat object.\n\nNull means the field was not returned for this company or jurisdiction.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID returned by the search endpoint.","schema":{"type":"integer"}},{"name":"include_provenance","in":"query","required":false,"description":"Add source metadata to the response. Recommended for audit and compliance workflows.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["company:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/{id}/officers":{"get":{"operationId":"officersKyb","tags":["People & ownership"],"summary":"List company officers","description":"Return current and former directors, officers, appointment dates, roles, published addresses, and available enrichment.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID returned by the search endpoint.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"One-based page number. Default 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results per page from 1 to 50. Default 10.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"include_provenance","in":"query","required":false,"description":"Add source metadata to the response. Recommended for audit and compliance workflows.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["company:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/officers/search":{"post":{"operationId":"officersSearchKyb","tags":["People & ownership"],"summary":"Search officers","description":"Search an individual by name and return the companies where they hold or previously held a statutory appointment.","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":500,"description":"Full or partial officer name; minimum two characters."},"date_of_birth_year":{"type":"integer","minimum":1000,"maximum":9999,"description":"Four-digit year used for disambiguation."},"country_code":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO alpha-2 country code."},"status":{"type":"string","enum":["C","P"],"description":"Current or previous appointment."},"appointment_date":{"$ref":"#/components/schemas/DateRange","description":"Inclusive YYYY-MM-DD appointment-date range."},"resignation_date":{"$ref":"#/components/schemas/DateRange","description":"Inclusive YYYY-MM-DD resignation-date range."},"company_name":{"type":"string","minLength":1,"description":"Optional company-name filter."},"company_reg_number":{"type":"string","minLength":1,"description":"Optional company-registration-number filter."},"company_status":{"type":"array","items":{"oneOf":[{"type":"integer"},{"type":"string","minLength":1}]},"description":"Company-status nomenclature IDs."},"company_countries":{"type":"array","items":{"oneOf":[{"type":"integer"},{"type":"string","minLength":1}]},"description":"KYB-country nomenclature IDs."},"include_provenance":{"type":"boolean","description":"Add source metadata to the response. Recommended for audit and compliance workflows."}},"required":["name"],"additionalProperties":false},"example":{"name":"Nicolae Buldumac","country_code":"GB"}}}},"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":[{"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"}]}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["company:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/{id}/shareholders":{"get":{"operationId":"shareholdersKyb","tags":["People & ownership"],"summary":"List disclosed shareholders","description":"Return direct shareholder names, quantities, percentages, share classes, prices, values, and currency where disclosed.\n\nA direct shareholder is not automatically an ultimate beneficial owner.\n\nAn empty response does not prove that a company has no shareholders; disclosure varies by jurisdiction.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID returned by the search endpoint.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"One-based page number. Default 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results per page from 1 to 50. Default 10.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"include_provenance","in":"query","required":false,"description":"Add source metadata to the response. Recommended for audit and compliance workflows.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["ownership:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/shareholders/search/{view_mode}":{"post":{"operationId":"shareholdersSearchKyb","tags":["People & ownership"],"summary":"Search shareholders","description":"Find companies linked to a named individual or corporate shareholder, with lite or full shareholding detail.","security":[{"bearerAuth":[]}],"parameters":[{"name":"view_mode","in":"path","required":true,"description":"Lite returns holder and company; full adds holding details.","schema":{"type":"string","enum":["lite","full"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":500,"description":"Shareholder name from 2 to 500 characters."},"company_name":{"type":"string","minLength":1,"description":"Optional company-name filter."},"registration_number":{"type":"string","minLength":1,"description":"Optional company-registration-number filter."},"vat_number":{"type":"string","minLength":1,"description":"Optional company VAT-number filter."},"location_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"ISO alpha-2 country filters."},"percentage":{"$ref":"#/components/schemas/PercentageRange","description":"Ownership range from 1 to 100."},"page":{"type":"integer","minimum":1,"default":1,"description":"One-based page number. Default 1."},"per_page":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Results per page from 1 to 50. Default 10."},"include_provenance":{"type":"boolean","description":"Add source metadata to the response. Recommended for audit and compliance workflows."}},"required":["name"],"additionalProperties":false},"example":{"name":"Nicolae Buldumac","location_countries":["GB"],"page":1,"per_page":10,"include_provenance":true}}}},"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["ownership:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/{id}/group-structures/lite":{"get":{"operationId":"groupLiteKyb","tags":["People & ownership"],"summary":"Get immediate group structure","description":"Return a simplified company hierarchy for quick parent and subsidiary checks.\n\nCorporate linkage is relationship data, not an automatic beneficial-owner conclusion.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID returned by the search endpoint.","schema":{"type":"integer"}},{"name":"include_provenance","in":"query","required":false,"description":"Add source metadata to the response. Recommended for audit and compliance workflows.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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/"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["ownership:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/{id}/group-structures/full":{"get":{"operationId":"groupFullKyb","tags":["People & ownership"],"summary":"Get complete group structure","description":"Return the available multi-level parent, subsidiary, and related-company hierarchy.\n\nDepth depends on available corporate-linkage evidence.\n\nDo not treat a terminal corporate node as a natural-person UBO without further ownership evidence.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID returned by the search endpoint.","schema":{"type":"integer"}},{"name":"include_provenance","in":"query","required":false,"description":"Add source metadata to the response. Recommended for audit and compliance workflows.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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/"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["ownership:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/{id}/financial":{"get":{"operationId":"financialKyb","tags":["Financials"],"summary":"Get filed financials","description":"Retrieve multi-year filed statements, metric groups, source values, and period-over-period progress indicators.\n\nMetric names vary by filing regime and accounting taxonomy.\n\nPreserve decimal precision and null values; do not coerce unavailable fields to zero.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID returned by the search endpoint.","schema":{"type":"integer"}},{"name":"include_provenance","in":"query","required":false,"description":"Add source metadata to the response. Recommended for audit and compliance workflows.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["financials:read"],"x-zephira-billing":"one_unit_on_success"}},"/kyb/{id}/full":{"get":{"operationId":"fullKyb","tags":["Complete profile"],"summary":"Get complete KYB record","description":"Retrieve company identity, officers, shareholders, full group structure, and financials in one response.\n\nThis route requires all three read scopes.\n\nFor latency-sensitive flows, call only the modules needed for the decision.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID returned by the search endpoint.","schema":{"type":"integer"}},{"name":"include_provenance","in":"query","required":false,"description":"Add source metadata to the response. Recommended for audit and compliance workflows.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful Zephira response. Jurisdiction-specific fields may also be present.","headers":{"X-Zephira-Request-Id":{"schema":{"type":"string"},"description":"Correlation ID for logs and support."},"Zephira-API-Version":{"schema":{"type":"string","const":"v1"}},"X-Zephira-Units":{"schema":{"type":"integer","const":1},"description":"Units charged for this successful request."},"X-Zephira-Remaining-Units":{"schema":{"type":"integer","minimum":0},"description":"Included workspace units remaining after this request."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"example":{"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":[]}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"405":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"x-zephira-scopes":["company:read","ownership:read","financials:read"],"x-zephira-billing":"one_unit_on_success"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"zph_live_…","description":"Create a scoped key in Dashboard → API keys."}},"schemas":{"Source":{"type":"object","properties":{"category":{"type":["string","null"]},"comment":{"type":["string","null"]},"id":{"type":["integer","string","null"]},"name":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"}},"additionalProperties":true},"DateRange":{"type":"object","properties":{"gte":{"type":"string","format":"date"},"lte":{"type":"string","format":"date"}},"anyOf":[{"required":["gte"]},{"required":["lte"]}],"additionalProperties":false},"PercentageRange":{"type":"object","properties":{"gte":{"type":"integer","minimum":1,"maximum":100},"lte":{"type":"integer","minimum":1,"maximum":100}},"anyOf":[{"required":["gte"]},{"required":["lte"]}],"additionalProperties":false},"Problem":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":false},"request_id":{"type":"string"},"documentation_url":{"type":"string","format":"uri"},"suggested_endpoints":{"type":"array","items":{"type":"object","required":["method","url","purpose"],"properties":{"method":{"type":"string"},"url":{"type":"string","format":"uri"},"purpose":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}},"responses":{"Problem":{"description":"Zephira error response. Failed requests consume zero units.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"x-zephira-field-policy":"All successful upstream KYB fields are preserved; absent or null fields remain absent or null."}