KYB

KYB ("Know Your Business") is how the org becomes a verified customer of the platform. Collect a unified superset of fields once and submit it. The orchestration layer handles the rest.

The dashboard is the canonical entry point for this flow. The endpoints here let automation tools mirror it (status polling, programmatic resubmission) and back the dashboard itself.

API keys can be minted at any point, they're separate from KYB. A key works for read-only and key-management endpoints from day one. Quoting, customer creation, and account creation become callable once the org is approved.

Organization verification endpoints require an admin or owner role in the selected organization, including profile, status, requests for information, and document reads. Other roles receive 403 Forbidden.

Endpoints

• GET /org/kyb/profile
• PUT /org/kyb/profile
• POST /org/kyb/submit
• GET /org/kyb/state
• GET /org/kyb/rfis
• POST /org/kyb/link
• POST /org/kyb/resync
• POST /org/kyb/documents
• GET /org/kyb/documents
• DELETE /org/kyb/documents/:id

KybProfile

The unified superset. Fields are grouped into subsections so partial saves stay manageable.

business

EntityType

One of:

• sole_proprietorship
• llc
• s_corporation
• c_corporation
• b_corporation
• non_profit
• partnership
• limited_partnership
• limited_liability_partnership
• trust
• dao
• cooperative
• other

addresses

contact

operations

Compliance/jurisdiction context.

SourceOfFunds

One of:

• salary
• savings
• business_revenue
• company_capital
• investment_returns
• inheritance
• trust
• gift
• grant
• sale_of_assets
• real_estate
• loan
• private_capital
• marital
• winnings
• other

RegulatedStatus

One of:

• regulated: set the regulated_* fields alongside.
• registered: set the regulated_* fields alongside.
• licensed: set the regulated_* fields alongside.
• not_required

AccountPurpose

Every value is accepted, but a business should pick from the recommended list — a purpose outside it can reach review as free text instead of a category, which clears slower. The KYB wizard offers exactly these, in this order; mirror it when you build your own form:

1. purchase_goods_and_services: pay for goods and services.
2. receive_payments_for_goods_and_services: receive payments for goods and services.
3. investment: make investments.
4. ecommerce_collections: accept retail e-commerce payments.
5. charitable_donations: make or receive charitable donations.
6. other: set account_purpose_explanation alongside.

Accepted, but not recommended for a business — these are consumer purposes, or duplicate a recommended value:

• crypto_investment: reviewed the same as investment. Send investment.
• payroll: paying employees or contractors. Reviewed the same as purchase_goods_and_services. Send that instead.
• remittances
• savings
• personal_use
• freelance_collections: collecting payment for freelance or contract work.
• salary_collections: receiving wages from an employer.
• business_operations: legacy. Accepted for existing integrations — submits as other with the purpose as account_purpose_explanation.
• treasury_management: legacy. Same handling as business_operations.

HighRiskActivity

One of:

• adult_entertainment
• gambling
• marijuana
• drugs
• firearms
• crypto_mixing: operating a crypto tumbler / mixer service.
• money_services
• lending_or_banking
• foreign_exchange
• hold_client_funds
• investment_services
• safe_deposit_box
• tobacco
• pharmaceuticals
• third_party_payment_processing
• none_of_the_above: explicit negative. Exclusive — sending it alongside any other value is rejected at submit. Send it on its own to disclose that none apply.

BusinessClassification

One of:

• marketplace: gig platforms, booking platforms, delivery apps, app stores.
• financial_services_provider: fintech companies, e.g. non-custodial neobanks, wallets, card programs, payment processors, remittance apps — including ones that never touch the flow of funds.
• none_of_the_above: explicit negative. Exclusive — sending it alongside any other value is rejected at submit. Send it on its own to disclose that none apply.

marketplace and financial_services_provider each imply acting_as_intermediary.

volumes

Estimated monthly transaction counts plus exact USD figures. Nonnegative. 0 is valid.

counterparties

CounterpartyType

One of:

• self_transactions
• merchants_suppliers
• customers
• employees
• contractors
• friends
• family

attestations

Submission-time attestations. Both must be true at submit.

associated_persons

Add all beneficial owners (individuals with ≥25% ownership) and directors. Every business must have at least one beneficial owner and at least one director, even if it is the same person.

At submit time:

• At least one entry is required.
• At least one entry must include "beneficial_owner" in its roles array.
• Every entry whose ownership_percent is 25 or more must include "beneficial_owner" in its roles array. Below 25 the role is optional.
• At least one entry must include "control_person" or "officer" in its roles array.
• At least one entry must include "authorized_signer" in its roles array.
• From November 14, 2026, every entry must also include at least one of "control_person", "officer", "director", or "authorized_signer". An entry whose only role is "beneficial_owner" is rejected with a violation on associated_persons[i].roles.
• Every entry must carry a full government-ID block (gov_id_kind, gov_id_number, gov_id_country, and gov_id_front_image_document_id), plus a selfie_document_id and a proof_of_address_document_id.
• Sum of ownership_percent across all entries must be ≤ 100. Sums under 100 are accepted: the residual represents holders below the disclosure threshold (per FinCEN's CDD rule, only ≥25% holders need be individually identified). Values accept up to two decimal places, so fractional stakes (e.g. three owners at "33.33" each) sum to 100 instead of being forced to whole numbers that overshoot.

customer_id — the field that ties an associated person to one of your individual customers — applies to your business customers' KYB profiles only. Sending it here is rejected.

SourceOfWealth

One of:

• salary
• dividends
• property_rental
• investment
• inheritance
• gambling
• donation

EconomicActivity

Multi-select. An entry can carry any combination.

• employed
• self_employed
• student
• gambler
• pensioner
• unemployed

AssociatedPersonRole

Multi-select. An entry can carry any combination.

• beneficial_owner: ≥25% direct or indirect ownership. At least one UBO across the entries must have this role.
• control_person: exercises significant control / management.
• officer: named officer (CEO, CFO, etc.). Sets title.
• director: board member.
• authorized_signer: empowered to sign on behalf of the entity.

GovIdKind

New submissions accept:

• passport
• drivers_license
• national_id

Existing profile reads can also return legacy values:

• residence_permit
• voters_card
• other

supplemental

Free-form entries for anything that doesn't fit the rest of the form — a text note or a supplemental document, each with a title and description. The section itself is optional at submit; the rules below apply to each entry sent. It is omitted from the response while empty, and profile saves are full-replace: a PUT /org/kyb/profile that omits supplemental clears the section, so echo the existing entries (with their ids) on every save they should survive.

Example

A complete KybProfile document:

{
  "business": {
    "legal_name": "Acme Inc.",
    "trade_name": "Acme",
    "description": "Acme Inc. operates a marketplace connecting suppliers and merchants worldwide.",
    "target_customers_description": "Mid-market suppliers and merchants in the US and Canada, typically 20-500 employees. They open accounts to collect marketplace payouts and pay their own suppliers from one balance. Around 30 inbound ACH settlements a month, and weekly outbound runs.",
    "entity_type": "c_corporation",
    "is_dao": false,
    "industry": "425120",
    "registration_number": "1234567",
    "tax_id": "82-1234567",
    "country_of_registration": "US",
    "state_of_incorporation": "DE",
    "formation_date": "2020-04-12",
    "website": "https://acme.example"
  },
  "addresses": {
    "registered": {
      "line1": "1 Wall St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10005",
      "country": "US"
    }
  },
  "contact": {
    "email": "ops@acme.com",
    "phone": "+12025550100",
    "phone_country_code": "US"
  },
  "operations": {
    "business_jurisdictions": ["US"],
    "funds_movement_jurisdictions": ["US", "GB"],
    "primary_source_of_funds": "company_capital",
    "regulated_status": "not_required",
    "account_purpose": "purchase_goods_and_services",
    "registered_msb": false,
    "licensed_vendors": true,
    "operates_in_prohibited_countries": false,
    "high_risk_activities": [
      "none_of_the_above"
    ],
    "business_classifications": [
      "financial_services_provider"
    ],
    "acting_as_intermediary": true,
    "in_flow_of_funds": false
  },
  "volumes": {
    "monthly_deposits": 35,
    "monthly_withdrawals": 30,
    "monthly_investment_deposit_usd": 0,
    "monthly_investment_withdrawal_usd": 0,
    "monthly_crypto_investment_deposit_usd": 0,
    "monthly_crypto_investment_withdrawal_usd": 0,
    "usd_value_of_fiat": 5000000,
    "usd_value_of_crypto": 0,
    "expected_monthly_payments_usd": 250000,
    "estimated_annual_revenue_usd": 5000000
  },
  "counterparties": {
    "counterparties": ["customers", "merchants_suppliers"]
  },
  "attestations": {
    "terms_and_conditions_accepted": true,
    "information_attested": true
  },
  "associated_persons": [
    {
      "first_name": "Alice",
      "middle_name": "Margaret",
      "last_name": "Liddell",
      "date_of_birth": "1985-06-15",
      "email": "alice@acme.com",
      "phone": "+12025550100",
      "phone_country_code": "US",
      "address": {
        "line1": "1 Wall St",
        "city": "New York",
        "state": "NY",
        "postal_code": "10005",
        "country": "US"
      },
      "tax_id": "123-45-6789",
      "nationality": "US",
      "citizenship": "US",
      "gender": "female",
      "country_of_birth": "US",
      "source_of_wealth": "salary",
      "previous_economic_activity": [
        "employed"
      ],
      "ownership_percent": "100",
      "roles": [
        "beneficial_owner",
        "officer",
        "director",
        "authorized_signer"
      ],
      "title": "CEO",
      "relationship_established_at": "2020-04-12",
      "gov_id_kind": "passport",
      "gov_id_number": "X12345678",
      "gov_id_country": "US",
      "gov_id_front_image_document_id": "8e3b…",
      "selfie_document_id": "c07a…",
      "proof_of_address_document_id": "b921…"
    }
  ],
  "supplemental": [
    {
      "id": "0e8b…",
      "kind": "text",
      "title": "Clarification on settlement volumes",
      "description": "Q3 volume increase reflects two new enterprise clients onboarded in July."
    },
    {
      "id": "7f1a…",
      "kind": "document",
      "title": "March bank statement",
      "description": "Statement covering the period referenced in the review.",
      "document_id": "b2c3…"
    }
  ]
}

When fields contain non-Latin-1 characters, supply the matching transliterated_* siblings. For example, an entity legally named in Japanese with a Japanese registered address would also send:

{
  "business": {
    "legal_name": "アクミ株式会社",
    "transliterated_legal_name": "Acme Kabushiki Kaisha",
    "trade_name": "アクミ",
    "transliterated_trade_name": "Acme"
  },
  "addresses": {
    "registered": {
      "line1": "東京都千代田区丸の内1-1-1",
      "city": "東京",
      "postal_code": "100-0005",
      "country": "JP",
      "transliterated_address": {
        "line1": "1-1-1 Marunouchi, Chiyoda-ku",
        "city": "Tokyo",
        "postal_code": "100-0005"
      }
    }
  }
}

Address

Shared shape used in addresses.registered, addresses.physical (via OperatingAddress), and associated_persons[].address. Adding the field to this type propagates to every site that references it. No need to repeat per-section.

No PO boxes.

Both conditional rules resolve per country. GET /customers/address-requirements answers them for one country ahead of submit, so a form can hide the fields that country's address format doesn't have.

OperatingAddress

addresses.physical only. Every Address field, sent inline.

operating_is_remote

Set addresses.operating_is_remote when the business has no office and the address it operates from is the residential address of a control person. Seismic adds a statement to that effect to the supplemental information document it sends to compliance review.

physical stays optional. Send it when the residence the business operates from is not the registered address already on the profile:

{
  "addresses": {
    "operating_is_remote": true,
    "physical": {
      "line1": "88 Cedar Ave",
      "city": "Austin",
      "state": "TX",
      "postal_code": "78701",
      "country": "US"
    }
  }
}

The flag and the operating address have to agree, in both directions. Only beneficial owners count — an associated_persons entry without the beneficial_owner role has no residence the business can be operating out of:

• With the flag set and a physical address sent, that address must match the address of one of the profile's beneficial owners — otherwise submission fails with an other violation on addresses.physical.
• When physical does match a beneficial owner's address, the flag must be set — otherwise submission fails with a not_in_allowed_set violation on addresses.operating_is_remote.

Addresses are compared as premises, not as strings: casing, extra whitespace and postal-code separators don't matter, but Ave and Avenue are different addresses.

Addresses sent without either flag read as operating_is_remote: false, so existing payloads are unaffected.

Country codes

Every country-valued field takes an ISO-3166-1 alpha-2 code: two uppercase letters, such as SG, US, GB. Country names are rejected — "Singapore" fails validation, "SG" is what the field wants. The same rule covers country_of_registration, phone_country_code, regulated_authority_country, nationality, citizenship, country_of_birth, gov_id_country, and the jurisdiction arrays.

City-states repeat the name across the address. city keeps the human-readable name ("Singapore"), country still takes the code ("SG"), and state is omitted because Singapore's address format has no state or region. Not every city-state drops state: Hong Kong's format includes an area, so HK addresses require one.

Correct:

{
  "line1": "1 Raffles Place",
  "city": "Singapore",
  "postal_code": "048616",
  "country": "SG"
}

Rejected:

{
  "line1": "1 Raffles Place",
  "city": "Singapore",
  "state": "Singapore",
  "postal_code": "048616",
  "country": "Singapore"
}

TransliteratedAddress

Latin-1 form of an address whose canonical fields contain non-Latin-1 characters (Cyrillic, CJK, Arabic, etc.). Sanctions / PEP screening runs against Latin-only databases, so the romanized form is required alongside the original. All-or-nothing: when the canonical address triggers the requirement, every required canonical field needs a Latin counterpart. country is omitted: ISO-3166 codes are always Latin-1.

KybState

Returned from GET /org/kyb/state, POST /org/kyb/submit, and POST /org/kyb/resync.