Global KYB Implementation Guide

New to Global KYB? Start with the Global KYB overview for what it does and how coverage works, then come back here for the full walkthrough. This guide covers international businesses — everywhere except Australia and the United States. Australian entities use the same API surface with an AU registration number; see the domestic KYB documentation. US entities have their own flow — see US Business Verification.

Prerequisites

An account with the kyb:api role, on the DEFAULT service.
API credentials — your api_key and X-Frankie-CustomerId.
Confirmation from your FrankieOne representative that international jurisdiction coverage is enabled for your account, and which countries are in your allowed list for profile and ownership (see Country restriction below).

Portal configuration (admins)

International KYB is switched on in Operations Center → Customers → [customer] → Configuration → KYB. Changes can take up to 10 minutes to take effect.

Portal Features tab — turn on KYB in Portal (enables KYB V2 in the Portal at all) and International KYB (the master switch for international organization search). With International KYB off, the Portal offers Australia only, regardless of the Countries tab.
Countries tab — one row per country, with four independent settings: Portal (whether the country is selectable in the Portal’s dropdowns), Lookup (whether the registry lookup call is allowed — the connector itself is chosen automatically: CreditorWatch for Australia, Kyckr everywhere else), Profile, and Ownership.

All four settings are independent, and a country needs all four turned on to work end to end. A country enabled for Portal but not for Profile lets an officer search the country, select a company, and then watch the workflow step fail with a country-restriction error. If a customer reports they can find a company but the workflow fails, this is the first thing to check.

Underlying config, for reference:

{
  "kyb_portal": {
    "international": {
      "enabled": true,
      "countries": ["AUS", "NZL", "SGP", "-USA"]
    }
  }
}

ISO 3166-1 alpha-3 codes; a - prefix excludes a country. Australia’s Portal setting is always on and cannot be removed.

Portal walkthrough

Step 1: Search for the business

From the organization search screen, select the country from the dropdown — this list only shows countries your account is configured to search — then search by name or registration number.

Selecting a country from the organization search dropdown.

Step 2: Review the result

Expand a result to view its full registry detail before creating the entity, so you can confirm you’ve selected the right organization. This comes from the same lookup response, with no extra loading step or additional cost.

Organization search results for a United Kingdom company, expanded to show registry details and a Create this entity button — A search result expanded to show its registry details.

Step 3: Create the entity and run a check

Creating the entity from a selected result and running Profile or Ownership works the same way as it does for a domestic entity. The Overview tab shows the registry-sourced profile once the workflow completes; sparse fields are expected for jurisdictions with lighter registry publishing, not a rendering fault.

The Overview tab once the workflow completes.

The Profile tab for an international organization.

Step 4: Review ownership

The Relationships tab shows Ultimate Beneficial Owners, Blocking Entities, Share Capital, and Officeholders, the same as domestic. Parties the registry couldn’t classify as an individual or organization appear with an explicit Unknown treatment rather than being hidden or mis-typed. If an ownership run hits its credit-cost ceiling before the tree fully resolves, the Relationships tab shows an in-progress or failure banner with a Continue report generation re-run option (gated on entity-write permission), and the entity where discovery stopped is flagged with the INSUFFICIENT_MAX_CREDIT_COST reason in the blocking-entities table. Re-running is a full new run rather than a resume, but running again within 24 hours reuses Kyckr’s already-cached profiles, so the search effectively goes deeper for the same budget. There’s no success toast; the in-progress banner is the feedback, and the officer stays on the Relationships tab. When manually associating a party as an Organisation, the officer now searches the relevant business registry by country, name, or registration number — free-text entry has been removed for organizations. Switching country clears the current selection and search text. This doesn’t apply to Individuals, which still take manual details.

Relationships tab showing owners and officeholders, with blocking entities whose reason is Entity type unknown — The Relationships tab, with Unknown parties listed as blocking entities.

Step 5: Generate a report

Generate a Profile Report or Ownership Report PDF from a completed workflow run, the same way as domestic. The template is selected automatically from the organization’s jurisdiction — there is no customer setting or API parameter for this.

Jurisdiction	Profile report	Ownership report
Australia	AU template (ABR/ASIC)	AU template
United States	US template	Generic template — there is no US-specific ownership design
Everywhere else	International Profile Report	Generic ownership report

The international profile report drops AU-only sections (ABR/ASIC extract, GST, state of registration, ANZSIC codes, historical business names) in favor of Industry Codes, Industry Declarations, Alternate Names, and Persons of Significant Control. AML screening results are deliberately never shown in a profile report — check the Portal for those. An empty section renders its heading with an explicit “none identified” message rather than being omitted.

Troubleshooting tip: if an international organization’s PDF unexpectedly shows ABR/ASIC fields, it was routed to the AU template — this happens when the organization’s jurisdiction country is empty and it also carries an AU marker (an ASIC registry reference, or an ABN/ACN-shaped registration number). The fix is to correct the entity’s jurisdiction data; the routing itself is working as designed.

API walkthrough

Step 1: Look up the business

Search a registry for a given region by name or registration number. Perform the lookup using the lookup organizations endpoint.

Request - Lookup by Name

curl --request POST \
    --url https://api.uat.frankie.one/v2/organizations/lookup \
    --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
    --header 'api_key: YOUR_API_KEY' \
    --header 'content-type: application/json' \
    --data '{
        "organizationName": "Acme Trading Ltd",
        "region": {
            "country": "GBR"
        }
    }'

Response - Lookup by Name

{
    "matchedOrganizations": [
        {
            "addresses": [
                {
                    "country": "GBR",
                    "unstructuredLongForm": "1 Example Street, London EC1A 1AA"
                }
            ],
            "alternateNames": [],
            "country": "GBR",
            "name": {
                "name": "ACME TRADING LTD"
            },
            "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjYtMDYtMTBUMDQ6Mzc6MDIuMDg3MDU3MzMzWiIsIm9uIjpbeyJybiI6IjEyMzQ1Njc4IiwicmEiOiJDT01QQU5JRVNfSE9VU0UifV0sInByb3YiOiJreWNrciIsImNvIjoiR0JSIn0=",
            "registrationDetails": [
                {
                    "registrationNumber": "12345678",
                    "registrationNumberType": "COMPANIES_HOUSE"
                }
            ],
            "type": {
                "description": "Private Limited Company"
            }
        }
    ],
    "queryDetails": {
        "organizationName": "Acme Trading Ltd",
        "region": { "country": "GBR" }
    },
    "requestId": "01K4RYKAYFKYY7JJVEX234B0FN"
}

Unlike a domestic AU lookup, an international result may not include status.normalized — Kyckr only provides a normalized legal status once a full profile is purchased, not at lookup time.

Lookup can return multiple matches. Extract the organizationToken from the match you intend to process — you’ll use it to create the entity in the next step.

Extracting the token

const organizationToken = response.matchedOrganizations[0].organizationToken;

Step 2: Create the organization

Create the entity from the organizationToken, using the create an organization entity endpoint.

Request - Create Organization

curl --location 'https://api.uat.frankie.one/v2/organizations' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjYtMDYtMTBUMDQ6Mzc6MDIuMDg3MDU3MzMzWiIsIm9uIjpbeyJybiI6IjEyMzQ1Njc4IiwicmEiOiJDT01QQU5JRVNfSE9VU0UifV0sInByb3YiOiJreWNrciIsImNvIjoiR0JSIn0=",
    "serviceName": "DEFAULT"
}'

Response - 201 Created

{
    "organization": {
        "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
        "entityType": "ORGANIZATION",
        "details": {
            "name": { "name": "ACME TRADING LTD" }
        },
        "schemaVersion": 2
    },
    "requestId": "01KWXT2THHWJ2EWPY7G6KQKRMY",
    "serviceProfiles": [
        {
            "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
            "serviceName": "DEFAULT",
            "serviceProfileId": "5cfdade0-71c7-4c7a-b348-2a53959a9caa",
            "state": "INIT"
        }
    ]
}

Retain the entityId — you need it for every subsequent call.

Step 3: Execute a workflow

Run GLB-Organization-Profile for registry details, or GLB-Organization-Ownership for the full beneficial-ownership tree. Both have Force-Refresh variants that always re-fetch instead of reusing recently cached provider data.

Request - Execute Workflow

curl --location 'https://api.uat.frankie.one/v2/organizations/workflows/GLB-Organization-Ownership/execute' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
    "serviceName": "DEFAULT"
}'

Response - Workflow Started

{
    "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
    "requestId": "01KWXT2VG40KSG1X0RKBJHPKZF",
    "serviceName": "DEFAULT",
    "serviceProfileId": "5cfdade0-71c7-4c7a-b348-2a53959a9caa",
    "workflowExecutionId": "01KWXT2WH7TZEZ6987AE9VB1TN"
}

Retain the workflowExecutionId to poll for the result.

Step 4: Poll for the result

Request - Get Workflow Execution

curl --location 'https://api.uat.frankie.one/v2/organizations/{entityId}/serviceprofiles/DEFAULT/workflows/GLB-Organization-Ownership/executions/{workflowExecutionId}' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'

Response - Execution Complete

{
    "workflowResult": {
        "workflowExecutionId": "01KWXT2WH7TZEZ6987AE9VB1TN",
        "workflowExecutionState": "COMPLETED",
        "status": "COMPLETE"
    }
}

State	Meaning
`IN_PROGRESS`	Still running — keep polling every few seconds.
`COMPLETED`	Finished. Retrieve the enriched organization and check the outcome.
`CANCELED` / `TERMINATED`	Ended before completion.
`ERROR` / `TIMEOUT`	Encountered an error, or timed out.

Check both fields. workflowExecutionState reports whether the execution finished; workflowResult.status carries the verification outcome (COMPLETE, REVIEW, FAIL, and others). A COMPLETED execution can still return an outcome such as REVIEW that needs a closer look — for an ownership run, that’s often INSUFFICIENT_MAX_CREDIT_COST on a blocking entity rather than a hard failure (see Credit budget below). Hitting the credit ceiling is not a failure: a partial tree is still returned.

Step 5: Retrieve the enriched organization

Request - Get Organization

curl --location 'https://api.uat.frankie.one/v2/organizations/{entityId}' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'

The response uses the same organization object as domestic entities. A few things behave differently for international results:

Field / behavior	What’s different internationally
`officials[].entityType`	May be `UNKNOWN` where the registry didn’t disclose whether a party is an individual or an organization. Never coerced to a guess.
`officials[].officialType`, PSC fields	Persons of Significant Control now carry their type and PSC attributes (kind, nature of control, notified-on date, nationality) on organizations fetched after this fix shipped. An organization whose data was fetched before then keeps its old shape until its next real re-fetch — a workflow re-run alone does not backfill this, since it reuses cached provider data within the ageing window.
`addresses[].country`	May be absent on a registry-sourced individual’s address (e.g. a director) — the registry doesn’t always supply one, and the platform will not guess it from the organization’s own country.
`ownership.beneficialOwners[].percentageOwned` / `otherOwners[].percentageOwned`	Carries `isBeneficialNearZero`, `isNonBeneficialNearZero`, `isTotalNearZero`, and `isContainingJointOwnership` flags when applicable, including for holdings that round to zero — the object is no longer dropped just because the percentages are all zero.

Step 6: Review AML and ownership insights

Run AML screening and review ownership insights the same way as domestic — the same policy engine, blocking definitions, and 25% UBO threshold apply. A few blocking reasons are distinctly international:

Blocking reason	When it fires internationally
`COUNTRY_NOT_SUPPORTED`	A sub-entity in the ownership chain sits in a jurisdiction Kyckr doesn’t serve. Common and expected — not a defect.
`ENTITY_TYPE_UNKNOWN`	Fires, but is threshold-gated at 25% — an UNKNOWN holding below that threshold is classified as an “other owner,” not a blocking entity.
`INSUFFICIENT_MAX_CREDIT_COST`	The UBO-discovery credit budget was exhausted before the tree fully resolved. Not a failure — the operation still returns a partial tree, with this reason on the entity where discovery stopped. See Credit budget below.

Country restriction

Profile and ownership coverage are each governed by a separate, per-customer allow-list. As currently deployed:

Profile — 76 countries by default.
Ownership — 15 countries by default, narrower than profile since recursive UBO coverage is narrower than basic company data.

The two lists are independent: an account can be allowed to pull a company profile in a country while UBO discovery there stays closed. A blocked country fails the check before any provider is called, so it costs nothing and raises no billing event; the workflow step ends in error naming the restriction, so it’s visible in the audit trail rather than looking like missing data. Contact your FrankieOne representative to review or change your account’s allowed countries.

Credit budget and ownership depth

Recursive UBO discovery works by ordering the focus company’s profile, unwrapping it to find shareholders, then ordering further profiles until every shareholder is identified, a blocking entity stops a branch, or the run’s configured credit ceiling is reached.

Hitting the ceiling is not a failure. The operation succeeds and returns a partial tree, with INSUFFICIENT_MAX_CREDIT_COST as the blocking reason on the entity where discovery stopped.
Company profiles requested in the last 24 hours are cached at no extra cost. Re-running ownership on the same company within that window effectively deepens the tree further, since the already-ordered profiles come from cache.
Results can only be retrieved for 30 days from creation.

Troubleshooting

Symptom	Explanation
Profile is mostly empty	Expected for jurisdictions with lighter registry publishing. Every field still renders, with a placeholder for anything not returned.
Shareholder or officer shows as Unknown	Expected — the registry didn’t disclose whether that party is an individual or an organization. Not an error.
Ownership tree looks shallow, or a blocking entity shows `INSUFFICIENT_MAX_CREDIT_COST`	The UBO-discovery credit budget was exhausted before the tree resolved. Re-run within 24 hours to reuse cached profiles and go deeper on the same budget, or ask your FrankieOne representative to raise the per-country credit ceiling.
A country is selectable in the Portal but a workflow step errors for it	The country is enabled for Portal display but not for Profile or Ownership. Ask your FrankieOne representative to check all four country settings.
An international organization’s PDF shows ABR/ASIC fields	It was routed to the AU report template — this happens when the organization’s jurisdiction is unset and it also carries an AU marker. Correct the entity’s jurisdiction data.

References

Global KYB overview — what’s covered, coverage tiers, and FAQs.
US Business Verification — the separate flow for US-registered businesses.
Understanding Organization Ownership — what the ownership fields on the organization object mean.
Interpreting Workflow Results — parse the full workflowResult object.
Anti-Money Laundering — screen the parties extracted from an ownership tree.

​Prerequisites

​Portal configuration (admins)

​Portal walkthrough

​Step 1: Search for the business

​Step 2: Review the result

​Step 3: Create the entity and run a check

​Step 4: Review ownership

​Step 5: Generate a report

​API walkthrough

​Step 1: Look up the business

​Step 2: Create the organization

​Step 3: Execute a workflow

​Step 4: Poll for the result

​Step 5: Retrieve the enriched organization

​Step 6: Review AML and ownership insights

​Country restriction

​Credit budget and ownership depth

​Troubleshooting

​References

Prerequisites

Portal configuration (admins)

Portal walkthrough

Step 1: Search for the business

Step 2: Review the result

Step 3: Create the entity and run a check

Step 4: Review ownership

Step 5: Generate a report

API walkthrough

Step 1: Look up the business

Step 2: Create the organization

Step 3: Execute a workflow

Step 4: Poll for the result

Step 5: Retrieve the enriched organization

Step 6: Review AML and ownership insights

Country restriction

Credit budget and ownership depth

Troubleshooting

References