KYB Compliance Flow

This guide explains how to integrate the KYB (Know Your Business) compliance system using both webhooks (push) and the Business Compliance Status API (pull).

Prerequisite: Related persons (UBOs, shareholders, representatives) must complete individual KYC before KYB can be finalized. See KYC Compliance Flow for the individual KYC integration guide.

Overview

The KYB system provides two complementary mechanisms:

Webhooks (Push): Real-time notifications when KYB state changes
Business Compliance Status API (Pull): On-demand status with actionable guidance

Use webhooks for real-time updates; use the API to get current state and determine next steps.

Integration Paths

Connect Financial supports two KYB integration strategies:

Strategy	Description	Availability
External KYB	You handle business verification with your own KYB process; Connect Financial stores documents and manages compliance gates	Available now
Standard (CF_KYB)	Business verification via Connect Financial's identity platform	Coming soon

This guide covers the External KYB flow. Standard KYB documentation will be published when that integration path is available.

Note: Your integration strategy is pre-configured at the account level by your Connect Financial account representative. It is not selected at runtime.

Webhook Events

Subscribe to these events via the Webhook API:

Event	When it fires	What it means
`CUSTOMER_KYB_STARTED`	`POST /v1/compliance/kyb` called	KYB process initiated
`CUSTOMER_KYB_FINISHED`	All compliance gates pass	KYB approved or denied (check `status` field)

Webhook Payload

{
  "eventType": "CUSTOMER_KYB_FINISHED",
  "data": {
    "customerId": "uuid",
    "status": "APPROVED",
    "businessOnboardingId": "uuid"
  }
}

Possible status values for CUSTOMER_KYB_FINISHED:

Status	Meaning
`APPROVED`	Business is fully compliant
`DENIED_COMPLIANCE`	Business failed compliance checks (e.g., a UBO's individual KYC was denied)

Business Compliance Status API

Endpoint: GET /v1/compliance/business/status/:customerId

Returns actionable business compliance data without requiring message parsing.

Response Structure

{
  "isCompliant": false,
  "onboardingStatus": "PROCESSING",
  "nextAction": "UPLOAD_BUSINESS_DOCUMENT",
  "checks": [
    {
      "type": "KYB_DATA_PRESENT",
      "passed": true,
      "required": true
    },
    {
      "type": "BUSINESS_DATA_COMPLETE",
      "passed": true,
      "required": true
    },
    {
      "type": "PERSON_RELATIONS_SHAREHOLDERS",
      "passed": true,
      "required": true
    },
    {
      "type": "UBO_KYC_COMPLETED",
      "passed": true,
      "required": true
    },
    {
      "type": "KYB_STARTED",
      "passed": true,
      "required": true
    },
    {
      "type": "SDK_VERIFICATION_COMPLETED",
      "passed": true,
      "required": false
    },
    {
      "type": "KYB_STATUS",
      "passed": false,
      "required": true,
      "suggestedAction": "UPLOAD_BUSINESS_DOCUMENT"
    },
    {
      "type": "DOC_CERTIF_INCORPORATION_REG",
      "passed": false,
      "required": true,
      "suggestedAction": "UPLOAD_BUSINESS_DOCUMENT"
    }
  ],
  "summary": {
    "passed": 15,
    "failed": 5,
    "requiredFailed": ["KYB_STATUS", "DOC_CERTIF_INCORPORATION_REG", "DOC_FATCA"]
  }
}

Suggested Action Values

Action	What to do
`UPDATE_BUSINESS_DATA`	Update business profile via `PATCH /v1/customers/business/:id` — check which data checks failed to determine what to update
`ADD_PERSON_RELATIONS`	Add shareholders or representatives via the person relations endpoints
`COMPLETE_UBO_KYC`	Related persons need individual KYC approval — see KYC Compliance Flow
`START_KYB`	Initiate KYB process via `POST /v1/compliance/kyb`
`UPLOAD_BUSINESS_DOCUMENT`	Upload required documents via `POST /v1/compliance/business/upload-document`
`WAIT`	No user action needed — system is processing
`CONTACT_SUPPORT`	Terminal failure (business denied, UBO KYC denied) — contact Connect Financial support
`NONE`	Fully compliant, no action needed

Check Types

Data & Person Checks

Check	Description	Required
`KYB_DATA_PRESENT`	Customer has KYB data submitted	Always
`BUSINESS_DATA_COMPLETE`	Required business fields present (legal name, tax number, tax country, address)	Always
`PERSON_RELATIONS_SHAREHOLDERS`	At least 1 shareholder with combined ownership ≥ 51%	Always
`PERSON_RELATIONS_REPRESENTATIVES`	At least 1 representative	Always
`UBO_KYC_COMPLETED`	All related persons have individual KYC approved	Always

KYB Process Checks

Check	Description	Required
`KYB_STARTED`	KYB process initiated via `POST /v1/compliance/kyb`	Always
`SDK_VERIFICATION_COMPLETED`	Identity verification completed	External KYB: not required (auto-passes)
`KYB_STATUS`	Overall KYB approved	Always

Document Checks — Corporate Account (10 required)

Check	Document	Description
`DOC_CERTIF_INCORPORATION_REG`	Certificate of Incorporation/Registration	Proof of business formation
`DOC_CORPORATE_RECORDS`	Corporate Records	Articles of association, organizational documents
`DOC_CORPORATE_RESOLUTION`	Corporate Resolution	Board resolution authorizing account opening
`DOC_COMPANY_FISCAL_REG_CERTIF`	Company Fiscal Registration Certificate	Tax registration certificate
`DOC_FATCA`	FATCA Declaration	W-8BEN-E (non-US) or W-9 (US) based on tax jurisdiction
`DOC_FINANCIAL_STATEMENTS`	Financial Statements	Recent financial statements or bank statement
`DOC_GOV_COMPANY_REG_NUMBER`	Government Company Registration Number	Government-issued business license/registration
`DOC_PROOF_OF_ADDRESS`	Proof of Address	Utility bill, bank statement, or similar
`DOC_SOURCE_OF_FUNDS`	Source of Funds	Declaration of business fund origins
`DOC_TAX_ID_NUMBER`	Tax ID Number	Tax identification document

Document Checks — Financial Institution Additional (15 required)

These additional documents are required only if the business is classified as a Financial Institution based on its NAICS sector code.

Check	Document	Description
`DOC_AML_CFT_SANCTIONS_IND_AUDIT`	AML/CFT Sanctions Independent Audit	Independent audit of AML/CFT sanctions compliance
`DOC_AML_CTF_SANCTIONS_POLICY`	AML/CTF Sanctions Policy	Anti-money laundering and counter-terrorism financing policy
`DOC_AML_CTF_TRAINING_PROGRAM`	AML/CTF Training Program	Staff training program for AML/CTF compliance
`DOC_AUTHORIZED_SIGNATURE_FORM`	Authorized Signature Form	Authorized signatory specimen card
`DOC_BANKING_LICENSE`	Banking License	Banking or financial services license
`DOC_BANKING_REFERENCE`	Banking Reference	Reference from existing banking relationship
`DOC_COMPLIANCE_DEPARTMENT`	Compliance Department	Compliance department organizational chart and procedures
`DOC_COMPLIANCE_OFFICER_RESUME`	Compliance Officer Resume	Compliance officer qualifications and experience
`DOC_FI_CORPORATE_STAMP`	FI Corporate Stamp	Financial institution corporate seal/stamp
`DOC_FI_LICENSE`	FI License	Financial institution regulatory license
`DOC_FINCEN_CERTIF_CORRESP_ACC_FI`	FinCEN Certification (Correspondent Account)	FinCEN certification for correspondent accounts
`DOC_GOOD_STANDING_CERTIFICATION`	Good Standing Certification	Certificate of good standing
`DOC_ML_TF_RISK_ASSESSMENT`	ML/TF Risk Assessment	Money laundering and terrorist financing risk assessment
`DOC_SHARE_CERTIFICATE`	Share Certificate	Share certificate documenting ownership structure
`DOC_WOLFSBERG_GCBDDQ`	Wolfsberg GCBDDQ	Wolfsberg Group Correspondent Banking Due Diligence Questionnaire

Handling `UPDATE_BUSINESS_DATA`

When nextAction is UPDATE_BUSINESS_DATA, one or more business data checks have failed. The checks array tells you exactly what is missing:

Failed Check	What to update via `PATCH /v1/customers/business/:id`
`KYB_DATA_PRESENT`	Provide the `kyb` object — legal name, tax information, identification, and address
`BUSINESS_DATA_COMPLETE`	Provide missing fields in the `kyb` object — check that `legalName`, `taxInformation`, `identification`, and `mainAddress` are all present

To determine what needs updating:

Call GET /v1/compliance/business/status/:customerId
Find checks where passed: false and suggestedAction: "UPDATE_BUSINESS_DATA"
Call PATCH /v1/customers/business/:id with the missing data

// Example: compliance status shows BUSINESS_DATA_COMPLETE failed
{
  "checks": [
    {
      "type": "BUSINESS_DATA_COMPLETE",
      "passed": false,
      "required": true,
      "suggestedAction": "UPDATE_BUSINESS_DATA"
    }
  ]
}

// Fix: PATCH /v1/customers/business/:id
{
  "kyb": {
    "legalName": "Acme Corporation",
    "legalStructureType": "LLC",
    "counterpartySectorCode": "541511",
    "industryDescription": "Custom Computer Programming Services",
    "taxInformation": {
      "number": "12-3456789",
      "taxNumberType": "TAX_IDENTIFICATION_NUMBER",
      "taxIdCountry": "US"
    },
    "identification": {
      "code": "BUS123456",
      "registrationDate": "2020-01-15",
      "documentIdCountry": "US"
    },
    "mainAddress": {
      "street1": "123 Business Ave",
      "street2": "Suite 100",
      "cityCounty": "New York",
      "stateRegion": "NY",
      "zip": "10001",
      "countryCode": "US"
    }
  }
}

Financial Institution Classification

A business is classified as a Financial Institution when its NAICS sector code matches any of the following. Financial Institutions must provide 25 documents (10 corporate + 15 additional) instead of the standard 10.

NAICS Code	Description
522 — Credit Intermediation
`522110`	Commercial Banking
`522120`	Savings Institutions
`522130`	Credit Unions
`522190`	Other Depository Credit Intermediation
`522210`	Credit Card Issuing
`522220`	Sales Financing
`522291`	Consumer Lending
`522292`	Real Estate Credit
`522293`	International Trade Financing
`522294`	Secondary Market Financing
`522298`	All Other Nondepository Credit Intermediation
`522310`	Mortgage and Nonmortgage Loan Brokers
`522320`	Financial Transactions Processing, Reserve, and Clearinghouse Activities
`522390`	Other Activities Related to Credit Intermediation
523 — Securities & Investments
`523110`	Investment Banking and Securities Dealing
`523120`	Securities Brokerage
`523130`	Commodity Contracts Dealing
`523140`	Commodity Contracts Brokerage
`523150`	Investment Banking and Securities Intermediation
`523210`	Securities and Commodity Exchanges
`523910`	Miscellaneous Intermediation
`523920`	Portfolio Management
`523930`	Investment Advice
`523991`	Trust, Fiduciary, and Custody Activities
`523999`	Miscellaneous Financial Investment Activities
524 — Insurance (select)
`524113`	Direct Life Insurance Carriers
`524114`	Direct Health and Medical Insurance Carriers
`524126`	Direct Property and Casualty Insurance Carriers
`524127`	Direct Title Insurance Carriers

If your business NAICS code does not appear in this list, you are classified as a Corporate Account and only the 10 baseline documents are required.

Person Relations

Person relations represent the individuals connected to the business — shareholders and representatives.

Constraints

The following constraints are evaluated during the auto-approval check (not at KYB start time):

Constraint	Requirement
Shareholders	At least 1 shareholder required
Ownership total	Shareholders' combined ownership must be ≥ 51%
Representatives	At least 1 representative required

Dual Roles

A single person can hold multiple roles simultaneously. For example, a CEO who is also the majority shareholder would be added twice — once as SHAREHOLDER with their ownership percentage, and once as REPRESENTATIVE.

Available Roles

Role	Description	Ownership Required
`SHAREHOLDER`	Owner/shareholder of the business	Yes (`ownershipPercentage` required)
`REPRESENTATIVE`	Authorized representative	No

Note: Only SHAREHOLDER and REPRESENTATIVE are valid roles. The API will reject any other role value (e.g., DIRECTOR) with a validation error.

Person Relations Endpoints

Method	Endpoint	Purpose
`POST`	`/v1/customers/business/:id/related-persons`	Add a person relation
`GET`	`/v1/customers/business/:id/related-persons`	List all person relations
`PATCH`	`/v1/customers/business/:id/related-persons`	Update a person relation
`DELETE`	`/v1/customers/business/:id/related-persons`	Remove a person relation

Important: Each related person must be created as an individual customer first via POST /v1/customers and must complete individual KYC before the business KYB can be finalized. See KYC Compliance Flow for the individual KYC process.

Individual KYC Requirement

All persons referenced in person relations must have approved individual KYC before the business can be approved. The system validates this at two points:

During auto-approval evaluation — the UBO_KYC_COMPLETED gate blocks approval if any UBO's KYC is not approved
When adding relations post-approval — once a business is APPROVED, adding a person whose individual KYC is not approved is rejected with HTTP 400: "Given that your KYB is approved, a related person must have approved individual KYC before being added as a related person"

Pre-approval note: Before KYB approval (PENDING or PROCESSING state), adding a person as a relation does NOT require their KYC to be approved. KYB start also does not require UBO KYC — you can start KYB and upload documents while individual KYC is still in progress. This allows parallel workflows and flexible profile building.

If a related person's individual KYC is denied, the business KYB is automatically set to DENIED_COMPLIANCE.

Source of Funds Declaration

The DOC_SOURCE_OF_FUNDS document can be satisfied in two ways:

Option 1: Upload your own document

Upload a Source of Funds declaration document directly:

POST /v1/compliance/business/upload-document
Headers:
  X-document-type: SOURCE_OF_FUNDS
  X-file-name: source-of-funds.pdf
  X-customer-id: {customerId}
Body: multipart/form-data with file

Option 2: Generate a declaration PDF

Use the built-in PDF generator to create a declaration from predefined source categories:

POST /v1/compliance/business/onboardings/:onboardingId/source-of-funds
Body:
{
  "sourcesOfFunds": ["income", "savings", "investments"]
}

This generates a PDF declaration, uploads it to the compliance system, and satisfies the DOC_SOURCE_OF_FUNDS requirement automatically.

Automatic Completion Triggers

The system continuously evaluates whether all compliance gates are met. Completion checks are automatically triggered after any of the following actions:

Trigger	What happens
Business data updated (`PATCH /v1/customers/business/:id`)	System re-checks all gates
Document uploaded (`POST /v1/compliance/business/upload-document`)	System re-checks all gates
Source of Funds PDF generated	System re-checks all gates
KYB started (`POST /v1/compliance/kyb`)	System re-checks all gates
UBO individual KYC approved	System automatically re-checks all non-terminal business onboardings referencing that person

Key insight: When a related person completes their individual KYC, the system automatically evaluates all business customers that reference them (both PENDING and PROCESSING states). If all gates pass (KYB started, documents uploaded, UBO KYC complete, shareholder %, representative present), the business is auto-approved.

When all gates pass (including KYB started and all documents uploaded), the business is automatically approved and a CUSTOMER_KYB_FINISHED webhook is fired with status: APPROVED.

Complete Integration Flow (External KYB)

┌───────────────────────────────────────────────────────────────────────────────────────┐
│ PHASE 1: Create Individual Persons (UBOs) + Start Individual KYC                      │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                       │
│   Client                              API                                  Webhook    │
│     │                                  │                                      │       │
│     │  For each person (shareholder,   │                                      │       │
│     │  representative               ): │                                      │       │
│     │                                  │                                      │       │
│     │──POST /v1/customers────────────▶│  (create individual customer)         │       │
│     │◀─────────────────────────────────│  { id: "person-uuid-1" }             │       │
│     │◀───────────────────────────────────────────────────CUSTOMER_CREATED─────│       │
│     │                                  │                                      │       │
│     │  (Complete individual KYC for    │                                      │       │
│     │   each person — see KYC guide)   │                                      │       │
│     │                                  │                                      │       │
│     │──POST /v1/compliance/kyc────────▶│                                      │       │
│     │◀──────────────────────────────────────────────CUSTOMER_KYC_STARTED──────│       │
│     │  ...Individual KYC flow ...      │                                      │       │
│     │◀──────────────────────────────────────────────CUSTOMER_KYC_FINISHED─────│       │
│     │                                  │  (status: APPROVED)                  │       │
│     │                                  │                                      │       │
│     │  Repeat for all related persons  │                                      │       │
│                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────────────────┐
│ PHASE 2: Create Business Customer                                                     │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                       │
│   Client                              API                                  Webhook    │
│     │                                  │                                      │       │
│     │──POST /v1/customers/business────▶│  (with KYB data)                     │       │
│     │◀─────────────────────────────────│  { id: "business-uuid" }             │       │
│     │◀───────────────────────────────────────────────────CUSTOMER_CREATED─────│       │
│     │                                  │                                      │       │
│     │──GET /compliance/business/status▶│                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │  KYB_DATA_PRESENT: true          │                                      │       │
│     │  BUSINESS_DATA_COMPLETE: true    │                                      │       │
│     │  PERSON_RELATIONS_*: false       │                                      │       │
│     │  nextAction: ADD_PERSON_RELATIONS│                                      │       │
│                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────────────────┐
│ PHASE 3: Add Person Relations                                                         │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                       │
│   Client                              API                                  Webhook    │
│     │                                  │                                      │       │
│     │──POST /customers/business/:id/──▶│  (shareholder with 51%)              │       │
│     │     related-persons              │                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │                                  │                                      │       │
│     │──POST /customers/business/:id/──▶│  (same person as representative)     │       │
│     │     related-persons              │                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │                                  │                                      │       │
│     │──GET /compliance/business/status▶│                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │  PERSON_RELATIONS_*: true        │                                      │       │
│     │  UBO_KYC_COMPLETED: true         │  (persons already KYC approved)      │       │
│     │  nextAction: START_KYB           │                                      │       │
│                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────────────────┐
│ PHASE 4: Start KYB                                                                    │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                       │
│   Client                              API                                  Webhook    │
│     │                                  │                                      │       │
│     │──POST /v1/compliance/kyb────────▶│  { customerId: "business-uuid" }     │       │
│     │◀─────────────────────────────────│  { onboardingId, status }            │       │
│     │◀──────────────────────────────────────────────CUSTOMER_KYB_STARTED──────│       │
│     │                                  │                                      │       │
│     │──GET /compliance/business/status▶│                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │  KYB_STARTED: true               │                                      │       │
│     │  SDK_VERIFICATION_COMPLETED:     │                                      │       │
│     │    passed: true, required: false │  ← Auto-passes for External KYB      │       │
│     │  DOC_* checks: false             │                                      │       │
│     │  nextAction: UPLOAD_BUSINESS_DOC │                                      │       │
│                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────────────────┐
│ PHASE 5: Upload Documents                                                             │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                       │
│   Client                              API                                  Webhook    │
│     │                                  │                                      │       │
│     │──POST /compliance/business/─────▶│  (Certificate of Incorporation)      │       │
│     │     upload-document              │                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │                                  │                                      │       │
│     │──POST /compliance/business/─────▶│  (Certificate of Good Standing)      │       │
│     │     upload-document              │                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │                                  │                                      │       │
│     │  ...upload remaining documents...│                                      │       │
│     │                                  │                                      │       │
│     │──POST /compliance/business/─────▶│  (Source of Funds - upload or        │       │
│     │     onboardings/:id/source-of-   │   generate via PDF endpoint)         │       │
│     │     funds                        │                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │                                  │                                      │       │
│     │──GET /compliance/business/status▶│                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │  All DOC_* checks: ✓             │                                      │       │
│     │  KYB_STATUS: false               │                                      │       │
│     │  nextAction: WAIT                │  (system processing)                 │       │
│                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────────────────┐
│ PHASE 6: Automatic Approval                                                           │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                       │
│   Client                              API                                  Webhook    │
│     │                                  │                                      │       │
│     │  (System auto-approves when      │                                      │       │
│     │   all gates pass: data complete, │                                      │       │
│     │   persons valid, UBO KYC done,   │                                      │       │
│     │   all docs uploaded)             │                                      │       │
│     │                                  │                                      │       │
│     │◀──────────────────────────────────────────────CUSTOMER_KYB_FINISHED─────│       │
│     │                                  │  (status: APPROVED)                  │       │
│     │                                  │                                      │       │
│     │──GET /compliance/business/status▶│                                      │       │
│     │◀─────────────────────────────────│                                      │       │
│     │  isCompliant: true               │                                      │       │
│     │  onboardingStatus: APPROVED      │                                      │       │
│     │  nextAction: null                │                                      │       │
│     │                                  │                                      │       │
│     │  Business customer ready for     │                                      │       │
│     │    virtual account creation      │                                      │       │
│                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────┘

Alternative Phase Ordering

The phases above show the recommended sequential order, but some phases can be performed in parallel or in different order:

Phase 1 and Phase 2 can happen in any order. You can create the business customer before or after creating the individual persons. What matters is that person relations reference valid individual customer IDs.
Person relations can be added at any time before starting KYB. You can add them immediately after creating the business customer or gradually over multiple API calls.
Documents must be uploaded after starting KYB (POST /v1/compliance/kyb). Attempting to upload documents before KYB is started returns HTTP 400 with "Customer's KYB needs to be started for upload to proceed".
Individual KYC must complete before KYB can be approved. You can start KYB and upload documents while individual KYC is still in progress. The auto-approval check will wait until all UBOs have approved KYC before approving the business.

Standard KYB Integration (Coming Soon)

Connect Financial will offer a Standard (CF_KYB) integration path where business identity verification is handled through Connect Financial's identity platform. This will include:

Identity verification SDK for business entities
Additional webhook events (CUSTOMER_KYB_SDK_FLOW_REQUIRED, CUSTOMER_KYB_SDK_EXPIRED, CUSTOMER_KYB_ERROR)
KYB rerun capability for expired or errored verifications

Contact your Connect Financial account representative for updates on availability.

Edge Case Flows

UBO Individual KYC Denied

When a related person's individual KYC is denied, the business KYB is automatically denied.

Webhook: CUSTOMER_KYC_FINISHED (for related person)
    │  (status: DENIED_COMPLIANCE)
    │
    ▼
System auto-denies business KYB
    │
    ▼
Webhook: CUSTOMER_KYB_FINISHED
    │  (status: DENIED_COMPLIANCE)
    │
    ▼
GET /compliance/business/status
    │
    ├─ onboardingStatus: DENIED_COMPLIANCE
    ├─ UBO_KYC_COMPLETED: false
    ├─ KYB_STATUS: false
    └─ nextAction: CONTACT_SUPPORT
    │
    ▼
Contact Connect Financial support

Note: Before KYB approval, adding a person as a relation does NOT require their KYC to be approved — the system allows adding non-KYC-approved persons during PENDING and PROCESSING states. No compliance constraints block KYB start — only business data completeness is validated. All compliance constraints (UBO KYC, shareholder %, representative) are enforced at auto-approval time. After KYB approval, adding a non-KYC-approved person is rejected (HTTP 400). Document uploads are also blocked while the business is in PENDING status — the upload endpoint returns HTTP 400 with "Customer's KYB needs to be started for upload to proceed".

Business Data Incomplete at KYB Start

If required business fields are missing when you call POST /v1/compliance/kyb, the request will fail.

POST /v1/compliance/kyb
    │  { customerId: "business-uuid" }
    │
    ▼
Error: Business data incomplete
    │
    ▼
GET /compliance/business/status
    │
    ├─ BUSINESS_DATA_COMPLETE: false
    └─ nextAction: UPDATE_BUSINESS_DATA
    │
    ▼
PATCH /v1/customers/business/:id
    │  (provide missing KYB fields)
    │
    ▼
GET /compliance/business/status
    │
    ├─ BUSINESS_DATA_COMPLETE: true
    └─ nextAction: START_KYB (or next required action)
    │
    ▼
(Continue from Phase 4)

Person Relations Constraints Not Met

If person relations don't satisfy constraints when starting KYB:

GET /compliance/business/status
    │
    ├─ PERSON_RELATIONS_SHAREHOLDERS: false
    │    suggestedAction: ADD_PERSON_RELATIONS
    │
    ├─ Possible reasons:
    │  • No shareholders added yet
    │  • Shareholders' combined ownership < 51%
    │  • No representatives added yet
    │
    └─ nextAction: ADD_PERSON_RELATIONS
    │
    ▼
Add/update person relations:
  POST /v1/customers/business/:id/related-persons
    │
    ▼
(Continue when constraints met)

Important: No compliance constraints block KYB start — only business data completeness is validated. If you call POST /v1/compliance/kyb with insufficient shareholders, missing representatives, or unapproved UBO KYC, KYB will start (status: PROCESSING) but will not auto-approve until all constraints are met. Compliance constraints (UBO KYC, shareholder %, representative) are enforced at auto-approval time.

Adding Unapproved Person During PROCESSING

If a non-KYC-approved person is added as a relation while the business is in PROCESSING state (after KYB start), the add succeeds but the business cannot auto-approve:

Business status: PROCESSING
    │
    ▼
POST /customers/business/:id/related-persons
    │  (add person without approved KYC)
    │
    ▼
HTTP 201 — Relation added successfully
    │
    ▼
GET /compliance/business/status
    │
    ├─ UBO_KYC_COMPLETED: false
    └─ nextAction: COMPLETE_UBO_KYC
    │
    ▼
Complete individual KYC for the new person
  (or remove the unapproved person)
    │
    ▼
Auto-approval re-evaluates when UBO KYC passes

Note: Adding an unapproved person during PROCESSING causes the UBO_KYC_COMPLETED check to regress to false. The business remains in PROCESSING and cannot approve until the new person completes KYC or is removed. The compliance status endpoint is the client's mechanism to detect this.

Duplicate Person Relations

The system prevents adding duplicate person relations (same user ID + same role):

POST /customers/business/:id/related-persons
    │  (userId: "abc", role: SHAREHOLDER — already exists)
    │
    ▼
HTTP 400: "Person relation already exists for userId=abc with role=SHAREHOLDER"

This applies in both pre-approval and post-approval states. The same person CAN hold multiple roles (e.g., SHAREHOLDER and REPRESENTATIVE) — see the Dual Roles section above.

Partial Document Upload

Documents can be uploaded incrementally. Each upload triggers an automatic completion check.

POST /compliance/business/upload-document
    │  (3 of 10 documents uploaded)
    │
    ▼
GET /compliance/business/status
    │
    ├─ DOC_CERTIF_INCORPORATION_REG: ✓
    ├─ DOC_CORPORATE_RECORDS: ✓
    ├─ DOC_CORPORATE_RESOLUTION: ✓
    ├─ DOC_COMPANY_FISCAL_REG_CERTIF: ✗
    ├─ ... (remaining unchecked)
    └─ nextAction: UPLOAD_BUSINESS_DOCUMENT
    │
    ▼
Continue uploading remaining documents
    │
    ▼
When last required document uploaded:
  System auto-triggers approval check
  → If all other gates pass → APPROVED
  → Webhook: CUSTOMER_KYB_FINISHED (status: APPROVED)

Overview​

Integration Paths​

Webhook Events​

Webhook Payload​

Business Compliance Status API​

Response Structure​

Suggested Action Values​

Check Types​

Data & Person Checks​

KYB Process Checks​

Document Checks — Corporate Account (10 required)​

Document Checks — Financial Institution Additional (15 required)​

Handling UPDATE_BUSINESS_DATA​

Financial Institution Classification​

Person Relations​

Constraints​

Dual Roles​

Available Roles​

Person Relations Endpoints​

Individual KYC Requirement​

Source of Funds Declaration​

Option 1: Upload your own document​

Option 2: Generate a declaration PDF​

Automatic Completion Triggers​

Complete Integration Flow (External KYB)​

Alternative Phase Ordering​

Standard KYB Integration (Coming Soon)​

Edge Case Flows​

UBO Individual KYC Denied​

Business Data Incomplete at KYB Start​

Person Relations Constraints Not Met​

Adding Unapproved Person During PROCESSING​

Duplicate Person Relations​

Partial Document Upload​