KYB Verification (Know Your Business)

Verify businesses and companies for KYB (Know Your Business) compliance. Includes company registry checks, beneficial ownership verification, and AML screening.

KYB checks are in preview and are available in the v1alpha2 API.

Overview

Use Case: Verify companies and businesses for compliance, onboarding, or due diligence purposes.

Key Features:

• Company registry verification (Companies House, etc.)
• Beneficial ownership identification
• AML screening of company and officers
• Financial checks and credit reports
• Adverse media screening
• No consumer interaction required (client provides company data)

Subject Type: Company/Organization

Template ID: checkTemplates/kyb-verification-check-v1-0-0

---

When to Use This Check

✅ Good for:

• Onboarding business clients
• Verifying companies for B2B transactions
• KYB compliance requirements
• Due diligence on business entities
• Beneficial ownership verification

❌ Not suitable for:

• Individual verification (use Identity Verification instead)
• Quick individual screening (use Client-Only Verification instead)
• Source of funds for individuals (use Source of Funds instead)

---

Prerequisites

• Thirdfort account with API access and KYB package
• Client credentials (Client ID and Secret)
• Company data: Company registration number, jurisdiction
• Package support: KYB verification requires specific package support

---

Search companies

Search companies by name, registration number or duns number. Used to retrieve an initial list of companies for a user to select from to perform a check.

Required Parameters

Parameter	Type	Description
jurisdiction	string	The jurisdiction (country) to search in

Oneof required parameters

One of the following must be provided as part of the company search

Parameter	Type	Description
name	string	The company name to search for
registrationNumber	string	The company registration number to search for
dunsNumber	string	The DUNS number to search for

Optional Parameters

Parameter	Type	Default	Description
state	string	""	The state or region within the jurisdiction
pageSize	integer	10	Number of results per page (Maximum 100) - currently ignored
pageToken	string	""	A page token, received from a previous SearchCompanies call - currently ignored

Note Paging is currently unsupported, pageSize and pageToken shall be ignored, pageToken shall always return as an empty string

---

Complete Example

curl --request POST \
  --url https://api.thirdfort.dev/client/api/v1alpha2/companies:search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "jurisdiction": "GB",
  "name": "ACME corp"
}'

---

Response

{
  "companies": [
    {
      "dunsNumber": "123456",
      "name": "ACME Corporation",
      "jurisdiction": "GB",
      "state": "",
      "registrationInfo": [
        {
          "registrationNumber": "123456",
          "typeDescription": "COMPANIES REGISTRY OFFICE Number (GB)"
        }
      ],
      "operatingStatus": "Active",
      "address": {
        "subBuilding": "",
        "buildingNumber": "",
        "buildingName": "ACME House",
        "street": "WB way",
        "subLocality": "",
        "locality": "CARTOONVILLE",
        "administrativeArea": "",
        "postalCode": "91505",
        "countryCode": "GB",
        "company": ""
      }
    },
    {
      "dunsNumber": "654321",
      "name": "ACME Anvils ltd",
      "jurisdiction": "GB",
      "state": "",
      "registrationInfo": [
        {
          "registrationNumber": "654321",
          "typeDescription": "COMPANIES REGISTRY OFFICE Number (GB)"
        }
      ],
      "operatingStatus": "Active",
      "address": {
        "subBuilding": "",
        "buildingNumber": "1",
        "buildingName": "",
        "street": "What's up Avenue",
        "subLocality": "",
        "locality": "TOONTOWN",
        "administrativeArea": "",
        "postalCode": "91522",
        "countryCode": "GB",
        "company": ""
      }
    }
  ],
  "nextPageToken": ""
}

---

Create Check

Create a KYB check, passed parameters should be derived from an initial Search Companies request

Required Parameters

Parameter	Type	Description
displayName	string	Human-readable name for the check
clientReference	string	Your own reference ID for tracking
template	string	Must be checkTemplates/kyb-verification-check-v1-0-0
params.@type	string	Must be type.googleapis.com/thirdfort.client.checks.type.v1alpha2.KYBVerificationCheckParams
params.subject.dunsNumber	string	Duns number of the company
params.subject.name	string	Legal name of the company
params.subject.jurisdiction	string	Jurisdiction/country code (e.g., "GB", "US")
params.packageType	enum	One of KYB_LITE or KYB

Optional Parameters

Parameter	Type	Default	Description
params.subject.registrationNumber	string	""	Company registration number
params.subject.registrationNumberType	string	""	Company registration type
params.subject.state	string	""	The state or region within the jurisdiction
params.initialDocumentRetrieval	list(KYBDocumentType)	[]	List of requested document types
params.enableOngoingMonitoring	bool	false	Continuous monitoring of screening results

---

Complete Example

curl -X POST "https://api.thirdfort.dev/client/api/v1alpha2/organizations/{org_id}/teams/{team_id}/checks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "KYB verification for Acme Corporation Ltd",
    "clientReference": "kyb-acme-12345",
    "template": "checkTemplates/kyb-verification-check-v1-0-0",
    "params": {
      "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.KYBVerificationCheckParams",
      "subject": {
        "name": "ACME Corporation",
        "dunsNumber": "123456",
        "jurisdiction": "GB"
      },
      "packageType": "KYB",
      "enableOngoingMonitoring": true
    }
  }'

Note: The endpoint includes the parent (team) in the URL path. Replace {org_id} and {team_id} with your actual organization and team IDs.

Response

{
  "name": "organizations/NT6bqXp6k47SbagGAUHHG7/teams/gZzg3caveKLhe3VXjRiyXL/checks/eaa99a49-7c7c-43e0-a929-ec2dddec8a85",
  "displayName": "KYB verification for Acme Corporation Ltd",
  "clientReference": "kyb-acme-12345",
  "state": "ACTIVE",
  "createTime": "2026-03-06T14:06:59.758655Z",
  "updateTime": null,
  "template": "checkTemplates/kyb-verification-check-v1-0-0",
  "params": { ... },
  "relatedSubjects": [ ... ],
  "creator": "partners/thirdfort/integrations/4",
  "ongoingMonitoring": {
    "enabled": true,
    "activeUntil": null
  },
  ...
}

Key Response Fields:

• name - Resource name of the check (use for subsequent API calls)
• state - Current check state (see Check States below)
• relatedSubjects - May include company officers and beneficial owners

Check States

• ACTIVE: The check is actively processing company data
• INACTIVE: The check has completed and results are available
• CANCELLED: The check has been permanently cancelled

Check summary

Complete Example

curl --request GET \
  --url https://api.thirdfort.dev/client/api/v1alpha2/organizations/{organization}/teams/{team}/checks/{check}/checkSummary \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Summary Response

{
  "name": "organizations/.../teams/.../checks/.../checkSummary",
  "createTime": "2026-03-06T14:07:00.537001Z",
  "payload": {
    "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.KYBVerificationCheckSummary",
    "overallRecommendation": {
      "recommendation": "CLEAR",
      "description": "No concerning issues found"
    },
    "pdfReportUrl": "http://...",
    "companyInformationResult": { ... },
    "companyOwnershipResult": { ... },
    "requestedPackageType": "KYB",
    "screeningResult": {...}
  },
  "sourceFindings": [ ... ],
  "reportUrl": "https://files.thirdfort.dev/client/downloads/objects/6ff46f10-ae87-42e6-8601-1f0c32ed5ba6",
  "summaryReportUrl": "https://files.thirdfort.dev/client/downloads/objects/8df632f9-e3f9-4e9e-88aa-ca449debf3b8"
}

Result Fields

Field	Description
payload.overallRecommendation	Overall check recommendation object with recommendation and description
payload.pdfReportUrl	The download URL for the PDF report
payload.companyInformationResult	The result of the company information check
payload.companyOwnershipResult	The result of the UBO/PSC ownership check
payload.requestedPackageType	The originally requested KYB package type (KYB_PACKAGE_TYPE_UNSPECIFIED, KYB_LITE or KYB)
payload.screeningResult	The result of the screening check
sourceFindings	Array of finding resource names that contributed to this summary
reportUrl	Download link for full PDF report
summaryReportUrl	Download link for summary PDF report

Recommendation Values

• CLEAR: No concerning issues were found. Results should still be reviewed before you rely on them
• CONSIDER: Anomalies detected that may be explainable - review findings
• FAIL: Serious anomalies detected, unlikely explainable - high risk

Downloading PDF Reports

Download PDF reports using the URLs from the summary:

# Download full PDF report
curl -X GET "https://files.thirdfort.dev/client/downloads/objects/6ff46f10-ae87-42e6-8601-1f0c32ed5ba6" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o kyb-report.pdf

# Download summary PDF report
curl -X GET "https://files.thirdfort.dev/client/downloads/objects/8df632f9-e3f9-4e9e-88aa-ca449debf3b8" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o kyb-summary.pdf

Note:

• PDF downloads require the same OAuth 2.0 access token used for API calls
• Use the complete URLs from reportUrl and summary.reportUrl fields directly
• URLs include /objects/ in the path

---

Jurisdiction Codes

Common jurisdiction codes:

• GB - United Kingdom (Companies House)
• US - United States
• DE - Germany
• FR - France
• IE - Ireland
• NL - Netherlands

---

Common flows

Simple PDF flow

The focus of this flow is simply to start a check, and retrieve the associated PDF.

1. If not already done so, authenticate and retrieve an oauth token
2. Use searchCompanies to present a list of companies against which a check may be made
3. Using the detail from a single searchCompanies response, perform a KYB create check
4. Request checkSummary, complete when CompanyInformation, CompanyOwnership and summary.reportUrl are populated
5. Retrieve PDF from summary.reportUrl

Webhook based PDF flow

In this flow a webhook is used to determine when PDF generation has occurred and retrieve the PDF.

1. If not already done so, authenticate and retrieve an oauth token
2. Use searchCompanies to present a list of companies against which a check may be made
3. Using the detail from a single searchCompanies response, perform a KYB create check
4. A notification shall be received with the type notification.client.report_generated.v1
5. Retrieve PDF using the URL in notification field reportUrl in the json body of the webhook

More details on registering for a webhook can be found here.

Note the notification type notification.client.report_generated.v1 will be generated whenever a PDF is generated. A PDF may be regenerated multiple times during a single check due to new data arriving or changes made by the client.

Best Practices

Verify Registration Number Format

Different jurisdictions have different registration number formats:

• UK: 8 digits (e.g., "12345678")
• US: Varies by state
• Germany: HRB/HRA + number

Verify the format matches the jurisdiction requirements.

---

Troubleshooting

Common Issues

400 Bad Request - "field required"

• Ensure displayName and clientReference are included
• Verify @type field is present in params
• Check that company name, dunsNumber, jurisdiction are provided

400 Bad Request - "invalid registration number"

• Verify registration number format matches jurisdiction
• Check for typos or extra characters
• Ensure jurisdiction code is correct

400 Bad Request - "company not found"

• Verify company exists in the registry
• Check registration number is correct
• Ensure jurisdiction is correct

Check takes longer than expected

• KYB checks can take minutes to hours
• Beneficial ownership verification adds time
• Financial checks may require additional data sources

404 Not Found

• Verify the endpoint includes parent in URL: /v1alpha2/{parent}/checks
• Check that organization and team IDs are correct
• Ensure endpoint is /checkSummary not /summary

---

Understanding Results

Get Check Summary

curl -X GET "https://api.thirdfort.dev/client/api/v1alpha2/organizations/{org_id}/teams/{team_id}/checks/{check_id}/checkSummary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Note: The endpoint is /checkSummary (camelCase), not /summary.