Skip to main content

​
KYB API - Detailed Documentation

This documentation covers Umbrella’s KYB (Know Your Business) APIs.
It provides two core capabilities:
  • Basic Search (/kyb/search) → Quickly resolve a company and return its canonical core profile (identity, status, type, identifiers, addresses, industry codes).
  • Advanced Company Details (/kyb/company/details) → Retrieve the full register-style record for a resolved company, including officers, ownership, relationships, signatory rules, contacts, and linked resources.
These endpoints are designed to return clean, decision-ready fields with both native register values and standardized modeled values (via the idcanopy scheme), enriched with metadata on confidence and completeness.

​
API Playground:

  • /kyb/search
  • /kyb/company/details
You can try the countries endpoint here.

​
Key Considerations

  • Contract Scope
    /kyb/search issues cached-first queries (≤30 days). All subsequent endpoints operate on the resolved companyId (Umbrella GUID). Identifiers such as registration number, VAT, or LEI are data fields only, not lookup keys.
  • Data Quality & Modeling
    Returns both native register values and standardized modeled values. Sources are labeled as native:register and idcanopy:modeled.
  • Visibility Modes
    • Minimal (default): returns a clean canonical payload with no provenance or conflicts.
    • Extended: adds field-level provenance, conflicts, and source attribution (for eligible tenants).

​
Endpoints Overview

  1. Search Company (/kyb/search): Resolve a company by name and country, and return its canonical core profile (identity, status, type, addresses, identifiers, industry codes).
  2. Company Details (/kyb/company/details): Retrieve the full register-style record for a resolved company, including officers, ownership, relationships, signatory rules, contacts, and linked resources.

​
Authentication

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.
  • Tokens are valid for 60 minutes and must be refreshed after expiration.
  • Refer to the Authentication for detailed steps on obtaining a token.
  • Include the token in the Authorization header as follows:
Authorization: Bearer YOUR_ACCESS_TOKEN

​
API Base URL

https://api-umbrella.io/api/services

​
Endpoint

POST /kyb/search

​
Description

Cached-first search for a company profile.
  • Uses Umbrella’s canonical company dataset.
  • On cache miss, queries providers and persists identity-only rows.
  • Returns decision-ready core attributes: name, type, status, identifiers, addresses, industry codes.

​
Required Headers

HeaderValue
Content-Typeapplication/json
Acceptapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

FieldTypeRequiredDescription
namestringYesRegistered name of the company.
countrystringYesTwo-letter ISO country code of company registration.
registrationNumberstringNoOfficial company registration number (may be empty).
localitystringYesCity or locality where the company is registered.

​
Response Structure

FieldTypeDescription
statusstringStatus of the request (e.g., success).
requestIdstringClient-provided request identifier for traceability.
companyIdstringUnique company identifier assigned by the platform.
timestampstringRFC 3339 timestamp when the response was generated.
dataobjectContains detailed company information.
data.company.legalNamestringOfficial registered legal name of the company.
data.company.tradingNamesarrayList of trading or alternative names.
data.company.statusstringCurrent company status (e.g., active, inactive).
native.valuestringNative company type value (e.g., Gesellschaft mit beschränkter Haftung).
native.languagestringLanguage code of the native type description.
native.sourcestringSource of the native type (e.g., register).
modeled.valuestringStandardized company type (e.g., Limited Liability Company).
modeled.schemestringScheme used for modeled classification (e.g., idcanopy).
modeled.sourcestringSource of the modeled type.
company.incorporationDatestringDate of incorporation (YYYY-MM-DD).
company.registrationDatestringDate of registration in the official register (YYYY-MM-DD).
company.countrystringTwo-letter ISO country code of incorporation.
registeredAddress.singleLinestringFull registered address as a single formatted string.
structured.line1stringStreet and building information.
structured.citystringCity of the registered address.
structured.postalCodestringPostal code of the registered address.
structured.countrystringCountry code of the registered address.
businessAddress.singleLinestringFull business/trading address as a single string.
structured.line1stringStreet and building information of business address.
structured.citystringCity of the business address.
structured.postalCodestringPostal code of the business address.
structured.countrystringCountry code of the business address.
company.identifiers[]arrayList of company identifiers across schemes.
identifiers[].schemestringIdentifier scheme (e.g., REGISTRATION_NUMBER, VAT, LEI).
identifiers[].valuestringIdentifier value.
identifiers[].countrystringCountry associated with the identifier.
company.industryCodes[]arrayList of industry classification codes.
industryCodes[].schemestringIndustry classification scheme (e.g., NACE).
industryCodes[].codestringIndustry code value.
industryCodes[].labelstringHuman-readable label of the industry code.
company.websitestringOfficial company website URL.
metadataobjectAdditional response metadata.
metadata.confidencenumberConfidence score for the company match (0–1).
metadata.completenessnumberCompleteness score for available company data (0–1).
metadata.cacheAgestringAge of cached response (e.g., 3h).

​
Example Request

{
  "name": "IDCANOPY GROUP LTD",
  "country": "GB",
  "registrationNumber": "",
  "locality": "London"
}

​
Example Response

{ 
  "status": "success", 
  "requestId": "client-req-987", 
  "companyId": "umb-7c9a-...", 
  "timestamp": "2025-08-25T08:00:00Z", 
  "data": { 
    "company": { 
      "legalName": "ACME GmbH", 
      "tradingNames": ["ACME"], 
      "status": "active", 
      "companyType": { 
        "native": {"value": "Gesellschaft mit beschränkter Haftung", "language": "de", "source": "register"}, 
        "modeled": {"value": "Limited Liability Company", "scheme": "idcanopy", "source": "modeled"} 
      }, 
      "incorporationDate": "2019-07-01", 
      "registrationDate": "2019-06-15", 
      "country": "AT", 
      "registeredAddress": { 
        "singleLine": "Musterstraße 1, 1010 Wien, AT", 
        "structured": { 
          "line1": "Musterstraße 1", 
          "city": "Wien", 
          "postalCode": "1010", 
          "country": "AT" 
        } 
      }, 
      "businessAddress": { 
        "singleLine": "Musterstraße 1, 1010 Wien, AT", 
        "structured": { 
          "line1": "Musterstraße 1", 
          "city": "Wien", 
          "postalCode": "1010", 
          "country": "AT" 
        } 
      }, 
      "identifiers": [ 
        {"scheme": "REGISTRATION_NUMBER", "value": "FN 123456x", "country": "AT"}, 
        {"scheme": "PR", "value": "930 B", "country": "DE"}, 
        {"scheme": "VAT", "value": "ATU12345678", "country": "AT"}, 
        {"scheme": "LEI", "value": "529900T8BM49AURSDO55"} 
      ], 
      "industryCodes": [ 
        {"scheme": "NACE", "code": "62.01", "label": "Computer programming activities"} 
      ], 
      "website": "https://acme.example" 
    } 
  }, 
  "metadata": { 
    "confidence": 0.93, 
    "completeness": 0.92, 
    "cacheAge": "3h" 
  } 
}

​
2. Advanced Company Details

​
Endpoint

POST /kyb/company/details

​
Description

Enrich a selected company by companyId.
  • Returns a full register-style record.
  • Includes officers, ownership, relationships, signatory rules, contacts, and company resources.
  • Completeness and provenance behave as specified (field-level provenance only in extended mode).

​
Required Headers

HeaderValue
Content-Typeapplication/json
Acceptapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

FieldTypeRequiredDescription
companyIdstringYesUnique identifier assigned to the company.

​
Response Structure

FieldTypeDescription
statusstringStatus of the request (e.g., success).
requestIdstringClient-provided request identifier.
companyIdstringUnique company identifier assigned by the platform.
timestampstringRFC 3339 timestamp when the response was generated.
dataobjectContains detailed company information.
company.legalNamestringRegistered legal name of the company.
company.tradingNamesarrayTrading or alternative names.
company.statusstringCompany status (e.g., active).
native.valuestringNative type value (e.g., Gesellschaft mit beschränkter Haftung).
native.languagestringLanguage code of the native type.
native.sourcestringSource of the native company type (e.g., register).
modeled.valuestringStandardized company type (e.g., Limited Liability Company).
modeled.schemestringScheme used for modeled classification (e.g., idcanopy).
modeled.sourcestringSource of the modeled type.
company.incorporationDatestringDate of incorporation (YYYY-MM-DD).
company.registrationDatestringDate of registration (YYYY-MM-DD).
company.countrystringISO 2-letter country code.
registeredAddress.singleLinestringRegistered address in single-line format.
structured.line1stringStreet and building of the registered address.
structured.citystringCity of the registered address.
structured.countrystringCountry of the registered address.
structured.postalCodestringPostal code of the registered address.
businessAddress.singleLinestringBusiness address in single-line format.
structured.line1stringStreet and building of the business address.
structured.citystringCity of the business address.
structured.postalCodestringPostal code of the business address.
structured.countrystringCountry of the business address.
company.identifiers[]arrayCompany identifiers across schemes.
identifiers[].schemestringIdentifier scheme (e.g., REGISTRATION_NUMBER, VAT, LEI).
identifiers[].valuestringIdentifier value.
identifiers[].countrystringCountry linked to the identifier.
company.industryCodes[]arrayIndustry classification codes.
industryCodes[].schemestringClassification scheme (e.g., NACE).
industryCodes[].codestringIndustry code.
industryCodes[].labelstringHuman-readable label of the industry code.
company.companyContacts[]arrayCompany contact details.
companyContacts[].websitestringWebsite URL.
companyContacts[].phonestringPhone number.
companyContacts[].faxstringFax number.
companyContacts[].emailstringEmail address.
companyContacts[].linkedinstringLinkedIn or social media profile.
companyContacts[].schemestringContact type scheme (e.g., homepage, phone, email, social media).
native.valuestringNative text of signatory rules.
native.languagestringLanguage of the native rule.
native.sourcestringSource of the native rule.
modeled.valuestringStandardized version of the rule.
modeled.schemestringScheme used for modeling.
modeled.sourcestringSource of the modeled rule.
company.companyResources[]arrayReferences to related company resources.
companyResources[].financialsstringReference ID for financials.
companyResources[].compliancestringReference ID for compliance.
companyResources[].ubostringReference ID for UBO details.
companyResources[].sanctionPePstringReference ID for sanctions/PEP details.
companyResources[].descriptionstringDescription of the resource.
company.officers[]arrayList of company officers.
officers[].typestringOfficer type (e.g., individual).
officers[].officerIDstringUnique officer ID.
officerData.firstNamestringOfficer’s first name.
officerData.lastNamestringOfficer’s last name.
officerData.DOBstringDate of birth (YYYY-MM-DD).
officerData.birthplacestringBirthplace of the officer.
officerData.countryOfBirthstringCountry of birth (ISO code).
officerData.nationalitystringNationality (ISO code).
address.singleLinestringOfficer’s address in single-line format.
PersonalNumber.identifierstringIdentifier value (e.g., PESEL number).
PersonalNumber.countrystringCountry of issuance of identifier.
PersonalNumber.schemestringIdentifier scheme (e.g., PESEL).
native.valuestringNative role (e.g., Geschäftsführer).
native.languagestringLanguage of native role.
native.sourcestringSource of native role.
modeled.valuestringStandardized officer role (e.g., Managing Director).
modeled.schemestringScheme for modeled role.
modeled.sourcestringSource of modeled role.
activity.statusstringOfficer’s current status (e.g., active).
activity.fromstringOfficer’s start date.
activity.tostringOfficer’s end date (if applicable).
native.valuestringNative signatory rights description.
native.languagestringLanguage of native signatory rights.
native.sourcestringSource of native rights.
modeled.valuestringStandardized signatory rights description.
modeled.schemestringScheme used for modeling.
modeled.sourcestringSource of modeled rights.
signatureRights.signatureQualitystringQuality/type of signature rights (e.g., individual).
data.company.ownership[]arrayList of company owners/shareholders.
ownership[].typestringType of owner (e.g., individual).
ownership[].ownerIDstringUnique owner ID.
ownerData.firstNamestringOwner’s first name.
ownerData.lastNamestringOwner’s last name.
address.singleLinestringOwner’s address.
holdingPct.sharesstringPercentage of shares held.
holdingPct.capitalstringAmount of capital held.
holdingPct.votingRightsstringPercentage of voting rights held.
verbalholding[].typestringType of holding description (e.g., shares).
native.valuestringNative description of holding.
native.languagestringLanguage of native description.
native.sourcestringSource of native description.
modeled.valuestringStandardized holding description.
modeled.schemestringScheme used for standardized holding.
modeled.sourcestringSource of standardized holding.
ownerData.isUBOstringIndicates if the owner is an Ultimate Beneficial Owner (e.g., yes).
relationships.ultimateBeneficialOwnersarrayList of UBOs.
relationships.transparencyRegisterarrayList of transparency register references.
relationships.familyTreearrayFamily tree relations.
relationships.isHeadquarterstringIndicates if the company is a headquarters.
relationships.isGlobalUltimatestringIndicates if the company is a global ultimate.
relationships.isDomesticUltimatestringIndicates if the company is a domestic ultimate.
relationships.isSubsidiarystringIndicates if the company is a subsidiary.
metadataobjectResponse metadata.
metadata.confidencenumberConfidence score for company match (0–1).
metadata.completenessnumberCompleteness score of available data (0–1).
metadata.sourcestringData source used (e.g., Handelsregister).
metadata.sourceTststringTimestamp when the source data was retrieved.
metadata.cacheAgestringAge of cached response (e.g., 3h).

​
Example Request

{
  "companyId": "123xyz"
}

​
Example Response

{ 
  "status": "success", 
  "requestId": "client-req-987", 
  "companyId": "umb-7c9a-...", 
  "timestamp": "2025-08-25T08:00:00Z", 
  "data": { 
    "company": { 
      "legalName": "ACME GmbH", 
      "tradingNames": ["ACME"], 
      "status": "active", 
      "companyType": { 
        "native": {"value": "Gesellschaft mit beschränkter Haftung", "language": "de", "source": "register"}, 
        "modeled": {"value": "Limited Liability Company", "scheme": "idcanopy", "source": "modeled"} 
      }, 
      "incorporationDate": "2019-07-01", 
      "registrationDate": "2019-06-15", 
      "country": "AT", 
      "registeredAddress": { 
        "singleLine": "Musterstraße 1, 1010 Wien, AT", 
        "structured": { 
          "line1": "Musterstraße 1", 
          "city": "Wien", 
          "postalCode": "1010", 
          "country": "AT" 
        } 
      }, 
      "businessAddress": { 
        "singleLine": "Musterstraße 1, 1010 Wien, AT", 
        "structured": { 
          "line1": "Musterstraße 1", 
          "city": "Wien", 
          "postalCode": "1010", 
          "country": "AT" 
        } 
      }, 
      "identifiers": [ 
        {"scheme": "REGISTRATION_NUMBER", "value": "FN 123456x", "country": "AT"}, 
        {"scheme": "PR", "value": "930 B", "country": "DE"}, 
        {"scheme": "VAT", "value": "ATU12345678", "country": "AT"}, 
        {"scheme": "LEI", "value": "529900T8BM49AURSDO55"} 
      ], 
      "industryCodes": [ 
        {"scheme": "NACE", "code": "62.01", "label": "Computer programming activities"} 
      ], 
      "companyContacts": [ 
        {"website": "https://acme.example", "scheme": "homepage"}, 
        {"phone": "0049123455", "scheme": "phone"}, 
        {"fax": "0049123456789", "scheme": "fax"}, 
        {"email": "office@acme.com", "scheme": "email"}, 
        {"linkedin": "https://linkedin.com/acme", "scheme": "social media"} 
      ], 
      "GlobalsignatoryRules": { 
        "native": {"value": "Jeder Partner vertritt die Gesellschaft allein.", "language": "de", "source": "register"}, 
        "modeled": {"value": "Every partner has sole representation rights", "scheme": "idcanopy", "source": "modeled"} 
      }, 
      "companyResources": [ 
        {"financials": "umbrelladetailuuid", "description": "financials reference"}, 
        {"compliance": "umbrelladetailuuid", "description": "compliance reference"}, 
        {"ubo": "umbrelladetailuuid", "description": "ubo reference"}, 
        {"sanctionPeP": "umbrelladetailuuid", "description": "sanctions/PEP reference"} 
      ], 
      "officers": [ 
        { 
          "type": "individual", 
          "officerID": "uuid", 
          "officerData": { 
            "firstName": "John", 
            "lastName": "Doe", 
            "DOB": "2000-01-01", 
            "birthplace": "Berlin", 
            "countryOfBirth": "DE", 
            "nationality": "DE", 
            "address": {"singleLine": "Musterstraße 1, 1010 Wien, AT"}, 
            "identityData": {"PersonalNumber": {"identifier": "asdfghj", "country": "PL", "scheme": "PESEL"}} 
          }, 
          "activity": { 
            "role": { 
              "native": {"value": "Geschäftsführer", "language": "de", "source": "register"}, 
              "modeled": {"value": "Managing Director", "scheme": "idcanopy", "source": "modeled"} 
            }, 
            "status": "active", 
            "from": "2000-01-01", 
            "to": "2000-01-01", 
            "signatureRights": { 
              "native": {"value": "Einzelvertretungsberechtigt", "language": "de", "source": "register"}, 
              "modeled": {"value": "Individual Representation", "scheme": "idcanopy", "source": "modeled"}, 
              "signatureQuality": "individual" 
            } 
          } 
        } 
      ], 
      "ownership": [ 
        { 
          "type": "individual", 
          "ownerID": "uuid", 
          "ownerData": { 
            "firstName": "John", 
            "lastName": "Doe", 
            "address": {"singleLine": "Musterstraße 1, 1010 Wien, AT"}, 
            "shareholding": { 
              "holdingPct": {"shares": "49.9%", "capital": "EUR 12500", "votingRights": "99%"}, 
              "verbalholding": [ 
                { 
                  "type": "shares", 
                  "native": {"value": "holds more than 25% but less than 50% of shares", "language": "en", "source": "register"}, 
                  "modeled": {"value": "SHARE 25-50", "scheme": "idcanopy", "source": "modeled"} 
                } 
              ] 
            }, 
            "isUBO": "yes" 
          } 
        } 
      ], 
      "relationships": { 
        "ultimateBeneficialOwners": ["loremIpsum"], 
        "transparencyRegister": [], 
        "familyTree": ["loremIpsum"], 
        "isHeadquarter": "Yes", 
        "isGlobalUltimate": "Yes", 
        "isDomesticUltimate": "Yes", 
        "isSubsidiary": "Yes" 
      } 
    } 
  }, 
  "metadata": { 
    "confidence": 0.93, 
    "completeness": 0.92, 
    "source": "Deutsches Handelsregister", 
    "sourceTst": "2025-08-25T08:00:00Z", 
    "cacheAge": "3h" 
  } 
}