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

Parameters Reference

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.company.name`	string	Legal name of the company
`params.company.registrationNumber`	string	Company registration number
`params.company.jurisdiction`	string	Jurisdiction/country code (e.g., "GB", "US")

Optional Parameters

Parameter	Type	Default	Description
`params.company.address`	Address	-	Registered address of the company
`params.company.incorporationDate`	Date	-	Date of incorporation (structured object: `{year, month, day}`)
`params.requireBeneficialOwnership`	bool	false	Identify and verify beneficial owners
`params.requireFinancialChecks`	bool	false	Include financial and credit checks
`params.requireAdverseMedia`	bool	false	Screen for adverse media mentions
`params.enableOngoingMonitoring`	bool	false	Continuous monitoring of company and officers

Complete Example

Create Check Request

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",
      "company": {
        "name": "Acme Corporation Ltd",
        "registrationNumber": "12345678",
        "jurisdiction": "GB",
        "address": {
          "buildingNumber": "100",
          "street": "Business Park",
          "locality": "London",
          "postalCode": "EC1A 1BB",
          "countryCode": "GBR"
        },
        "incorporationDate": {
          "year": 2015,
          "month": 3,
          "day": 15
        }
      },
      "requireBeneficialOwnership": true,
      "requireFinancialChecks": true,
      "requireAdverseMedia": true,
      "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

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"
    },
    "companyRegistryResult": { ... },
    "beneficialOwnershipResult": { ... },
    "screeningCheckResult": { ... },
    "financialChecksResult": { ... },
    "adverseMediaResult": { ... },
    "providedCompanyData": { ... }
  },
  "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.companyRegistryResult`	Company registry verification results - always included
`payload.beneficialOwnershipResult`	Beneficial ownership results - only if `requireBeneficialOwnership: true`
`payload.screeningCheckResult`	AML screening of company and officers - always included
`payload.financialChecksResult`	Financial and credit check results - only if `requireFinancialChecks: true`
`payload.adverseMediaResult`	Adverse media screening results - only if `requireAdverseMedia: true`
`payload.providedCompanyData`	Echo of the company data you provided
`reportUrl`	Download link for full PDF report (top-level field)
`summaryReportUrl`	Download link for summary PDF report (top-level field)
`sourceFindings`	Array of finding resource names that contributed to this summary

Recommendation Values

CLEAR: No concerning issues found - proceed with confidence
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 summaryReportUrl fields directly
URLs include /objects/ in the path

Company Data Format

Company Object

{
  "company": {
    "name": "Acme Corporation Ltd",
    "registrationNumber": "12345678",
    "jurisdiction": "GB",
    "address": {
      "buildingNumber": "100",
      "street": "Business Park",
      "locality": "London",
      "postalCode": "EC1A 1BB",
      "countryCode": "GBR"
    },
    "incorporationDate": {
      "year": 2015,
      "month": 3,
      "day": 15
    }
  }
}

Required Fields:

name - Legal name of the company
registrationNumber - Company registration number (format varies by jurisdiction)
jurisdiction - ISO 3166-1 alpha-2 country code (e.g., "GB", "US", "DE")

Optional Fields:

address - Registered address
incorporationDate - Date of incorporation

Jurisdiction Codes

Common jurisdiction codes:

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

Common Configurations

Basic KYB Verification

Minimal configuration for company verification:

{
  "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",
    "company": {
      "name": "Acme Corporation Ltd",
      "registrationNumber": "12345678",
      "jurisdiction": "GB"
    }
  }
}

With Beneficial Ownership

Identify and verify beneficial owners:

{
  "params": {
    "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.KybVerificationCheckParams",
    "company": { ... },
    "requireBeneficialOwnership": true
  }
}

Comprehensive KYB Check

Full verification with all optional checks:

{
  "params": {
    "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.KybVerificationCheckParams",
    "company": { ... },
    "requireBeneficialOwnership": true,
    "requireFinancialChecks": true,
    "requireAdverseMedia": true,
    "enableOngoingMonitoring": true
  }
}

Best Practices

Provide Complete Company Data

Include all available information:

{
  "company": {
    "name": "Acme Corporation Ltd",
    "registrationNumber": "12345678",
    "jurisdiction": "GB",
    "address": {
      "buildingNumber": "100",
      "street": "Business Park",
      "locality": "London",
      "postalCode": "EC1A 1BB",
      "countryCode": "GBR"
    },
    "incorporationDate": {
      "year": 2015,
      "month": 3,
      "day": 15
    }
  }
}

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.

Beneficial Ownership

When requireBeneficialOwnership: true:

The check will identify individuals with >25% ownership
Each beneficial owner will be screened for sanctions/PEP
Results will include beneficial owner details

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, registrationNumber, and 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.

Overview​

When to Use This Check​

Prerequisites​

Parameters Reference​

Required Parameters​

Optional Parameters​

Complete Example​

Create Check Request​

Response​

Check States​

Summary Response​

Result Fields​

Recommendation Values​

Downloading PDF Reports​

Company Data Format​

Company Object​

Jurisdiction Codes​

Common Configurations​

Basic KYB Verification​

With Beneficial Ownership​

Comprehensive KYB Check​

Best Practices​

Provide Complete Company Data​

Verify Registration Number Format​

Beneficial Ownership​

Troubleshooting​

Common Issues​

Understanding Results​

Get Check Summary​