--- title: "Submit KYB data" method: POST path: "/v1/organizations/{organization_id}/kyb/submit" tags: ["Fiat"] --- # Submit KYB data `POST /v1/organizations/{organization_id}/kyb/submit` ## Request - Base URL: `https://api.privy.io` - URL: `https://api.privy.io/v1/organizations/{organization_id}/kyb/submit` - Auth: HTTP basic Submits KYB verification data for the organization. Safe to call more than once: the first call creates the provider customer and later calls update it, so a partial submission can be completed incrementally. ## Path parameters - `organization_id` string, required: The ID of the organization. ## Headers - `privy-app-id` string, required: ID of your Privy app. ## Request body - KybSubmitRequestBody: Request body for headless KYB data submission. - `provider` 'bridge', required: KYC/KYB provider identifier. - `environment` 'production' | 'sandbox': Provider environment (production or sandbox). - `endorsements` KyxEndorsementName[]: Endorsements to request during KYB. - `client_agreement_id` string: Client-side agreement ID for ToS acceptance. - `data` KybSubmitData, required: KYB verification data for headless submission. Fields are individually optional because the provider accepts partial submissions and grants endorsements once enough data has arrived; a partial submission can be completed by calling the endpoint again. - `business_legal_name` string: Registered legal name as filed with government authorities. - `business_trade_name` string: Public trading name (DBA), if different from the legal name. - `transliterated_business_legal_name` string: Latin-1 transliteration of the legal name. Required for non-Latin-1 names. - `transliterated_business_trade_name` string: Latin-1 transliteration of the trade name. Required for non-Latin-1 names. - `business_description` string: Short summary of what the business does. - `business_type` string: Legal structure of the business. Passthrough to the provider. See the [Bridge customer API reference](https://apidocs.bridge.xyz/platform/customers/customers/api) for accepted values. - `business_industry` string[]: 2022 NAICS codes describing the industries the business operates in. - `email` string, email: Primary business email address. - `phone` string: Business phone number in E.164 format. - `incorporation_date` string: Date of incorporation in YYYY-MM-DD format. - `is_dao` boolean: Whether the business is a decentralized autonomous organization. - `primary_website` string: Primary website. If omitted, a proof_of_nature_of_business document is required. - `other_websites` string[]: Additional websites and social handles. - `registered_address` VerificationAddress: A postal address used in KYC and KYB data submission. - `street_line_1` string, required: Street address line 1. - `street_line_2` string: Street address line 2. - `city` string, required: City. - `subdivision` string: ISO 3166-2 state or province code. Required for US addresses. - `postal_code` string: Postal code. Required for countries that use them. - `country` string, required: ISO 3166-1 alpha-3 country code. - `physical_address` VerificationAddress: A postal address used in KYC and KYB data submission. - `street_line_1` string, required: Street address line 1. - `street_line_2` string: Street address line 2. - `city` string, required: City. - `subdivision` string: ISO 3166-2 state or province code. Required for US addresses. - `postal_code` string: Postal code. Required for countries that use them. - `country` string, required: ISO 3166-1 alpha-3 country code. - `transliterated_registered_address` VerificationAddress: A postal address used in KYC and KYB data submission. - `street_line_1` string, required: Street address line 1. - `street_line_2` string: Street address line 2. - `city` string, required: City. - `subdivision` string: ISO 3166-2 state or province code. Required for US addresses. - `postal_code` string: Postal code. Required for countries that use them. - `country` string, required: ISO 3166-1 alpha-3 country code. - `transliterated_physical_address` VerificationAddress: A postal address used in KYC and KYB data submission. - `street_line_1` string, required: Street address line 1. - `street_line_2` string: Street address line 2. - `city` string, required: City. - `subdivision` string: ISO 3166-2 state or province code. Required for US addresses. - `postal_code` string: Postal code. Required for countries that use them. - `country` string, required: ISO 3166-1 alpha-3 country code. - `ownership_threshold` integer: Ownership percentage at which a person is treated as a beneficial owner. - `has_material_intermediary_ownership` boolean: Whether an intermediate entity owner holds 25% or more of the business. - `publicly_traded_listings` KybPubliclyTradedListing[]: Public exchange listings for the business. - `market_identifier_code` string, required: ISO 10383 market identifier code of the listing venue. - `stock_number` string, required: ISIN with dashes removed. - `ticker` string, required: Exchange ticker symbol. - `associated_persons` KybAssociatedPerson[]: Beneficial owners, control persons, and signers. - `first_name` string, required: Legal first name. - `middle_name` string: Legal middle name. - `last_name` string, required: Legal last name. - `transliterated_first_name` string: Latin-1 transliteration of the first name. Required for non-Latin-1 names. - `transliterated_middle_name` string: Latin-1 transliteration of the middle name. Required for non-Latin-1 names. - `transliterated_last_name` string: Latin-1 transliteration of the last name. Required for non-Latin-1 names. - `email` string, email, required: Email address. - `phone` string: Phone number in E.164 format. - `date_of_birth` string, required: Date of birth in YYYY-MM-DD format. Must be 18 years or older. - `residential_address` VerificationAddress, required: A postal address used in KYC and KYB data submission. - `street_line_1` string, required: Street address line 1. - `street_line_2` string: Street address line 2. - `city` string, required: City. - `subdivision` string: ISO 3166-2 state or province code. Required for US addresses. - `postal_code` string: Postal code. Required for countries that use them. - `country` string, required: ISO 3166-1 alpha-3 country code. - `transliterated_residential_address` VerificationAddress: A postal address used in KYC and KYB data submission. - `street_line_1` string, required: Street address line 1. - `street_line_2` string: Street address line 2. - `city` string, required: City. - `subdivision` string: ISO 3166-2 state or province code. Required for US addresses. - `postal_code` string: Postal code. Required for countries that use them. - `country` string, required: ISO 3166-1 alpha-3 country code. - `identifying_information` VerificationDocument[], required: Identifying documents for this person. - `type` string, required: Document type identifier. - `issuing_country` string, required: ISO 3166-1 alpha-3 issuing country code. - `number` string: Document number. - `description` string: Document description. - `expiration` string: Document expiration date. - `image_front` string: Base64-encoded front image. - `image_back` string: Base64-encoded back image. - `has_ownership` boolean, required: Whether this person owns 25% or more of the business. - `has_control` boolean, required: Whether this person is a control person. - `is_signer` boolean, required: Whether this person is a signer for the business. - `is_director` boolean: Whether this person is a director. - `title` string: Job title. Required when has_control is true. - `ownership_percentage` integer: Percentage of the business this person owns. - `nationalities` string[]: ISO 3166-1 alpha-3 codes for all nationalities held. - `place_of_birth` KybPlaceOfBirth: Place of birth for an associated person. - `country` string, required: ISO 3166-1 alpha-3 country code. - `city` string: City of birth. - `relationship_established_at` string: Date the relationship with the business was established, in YYYY-MM-DD format. - `documents` KybIndividualDocument[]: Supporting documents for this person, such as proof of address. - `purposes` KybIndividualDocumentPurpose[], required: What this document evidences. Supports multiple purposes per file. - `file` string, required: Base64-encoded data URI of the document. - `description` string: Document description. Required when "other" is one of the purposes. - `kyc_screen` KyxScreen: Result of a KYC/AML or OFAC screen you performed and are relying on the provider to accept, honoured only for developers enrolled in reliance. - `screened_at` union, required: When the screen was performed (ISO 8601 date or date-time). - string, date-time - string, date - `result` 'passed' | 'failed', required: Outcome of a screen performed under KYC/KYB reliance. - `ofac_screen` KyxScreen: Result of a KYC/AML or OFAC screen you performed and are relying on the provider to accept, honoured only for developers enrolled in reliance. - `screened_at` union, required: When the screen was performed (ISO 8601 date or date-time). - string, date-time - string, date - `result` 'passed' | 'failed', required: Outcome of a screen performed under KYC/KYB reliance. - `verified_database_at` union: When you verified this person against a database source (ISO 8601). - string, date-time - string, date - `verified_govid_at` union: When you verified the government ID for this person (ISO 8601). - string, date-time - string, date - `verified_proof_of_address_at` union: When you verified proof of address for this person (ISO 8601). - string, date-time - string, date - `attested_ownership_structure_at` union: When this person (a control person) attested to having verified the business ownership structure (ISO 8601). - string, date-time - string, date - `estimated_annual_revenue_usd` string: Estimated annual revenue of the business, in USD buckets. Passthrough to the provider. See the [Bridge customer API reference](https://apidocs.bridge.xyz/platform/customers/customers/api) for accepted values. - `expected_monthly_payments_usd` integer: Expected monthly payment volume in USD. Required for high-risk businesses. - `source_of_funds` string: Primary source of the funds the business will transact with. Passthrough to the provider. See the [Bridge customer API reference](https://apidocs.bridge.xyz/platform/customers/customers/api) for accepted values. - `source_of_funds_description` string: Free-text detail on the source of funds. Required for high-risk businesses. - `account_purpose` string: Primary purpose the business will use the account for. Passthrough to the provider. See the [Bridge customer API reference](https://apidocs.bridge.xyz/platform/customers/customers/api) for accepted values. - `account_purpose_other` string: Free-text purpose. Required when account_purpose is "other". - `acting_as_intermediary` boolean: Whether the business moves funds on behalf of third parties. - `operates_in_prohibited_countries` boolean: Whether the business operates in prohibited jurisdictions. - `high_risk_activities` KybHighRiskActivity[]: High-risk activities the business engages in. - `high_risk_activities_explanation` string: Explanation of the high-risk activities. Required unless the only value is "none_of_the_above". - `conducts_money_services` boolean: Whether the business conducts money services. - `conducts_money_services_using_bridge` boolean: Whether money services are conducted through the provider. Requires a flow_of_funds document when true. - `conducts_money_services_description` string: Description of the money services conducted. - `compliance_screening_explanation` string: Description of the AML and sanctions screening controls in place. - `has_foreign_tax_registration` boolean: Whether the business is tax-registered outside its country of incorporation. - `regulated_activity` KybRegulatedActivity: Details of the regulated activity a business is licensed to perform. - `regulated_activities_description` string, required: Description of the regulated activities performed. - `primary_regulatory_authority_country` string, required: ISO 3166-1 alpha-3 country code of the primary regulator. - `primary_regulatory_authority_name` string, required: Name of the primary regulator. - `license_number` string, required: License number issued by the regulator. - `identifying_information` VerificationDocument[]: Business tax and registration identifiers. - `type` string, required: Document type identifier. - `issuing_country` string, required: ISO 3166-1 alpha-3 issuing country code. - `number` string: Document number. - `description` string: Document description. - `expiration` string: Document expiration date. - `image_front` string: Base64-encoded front image. - `image_back` string: Base64-encoded back image. - `documents` KybBusinessDocument[]: Supporting documents for verification. - `purposes` KybDocumentPurpose[], required: What this document evidences. Supports multiple purposes per file. - `file` string, required: Base64-encoded data URI of the document. - `description` string: Document description. Required when "other" is one of the purposes. - `kyb_screen` KyxScreen: Result of a KYC/AML or OFAC screen you performed and are relying on the provider to accept, honoured only for developers enrolled in reliance. - `screened_at` union, required: When the screen was performed (ISO 8601 date or date-time). - string, date-time - string, date - `result` 'passed' | 'failed', required: Outcome of a screen performed under KYC/KYB reliance. - `ofac_screen` KyxScreen: Result of a KYC/AML or OFAC screen you performed and are relying on the provider to accept, honoured only for developers enrolled in reliance. - `screened_at` union, required: When the screen was performed (ISO 8601 date or date-time). - string, date-time - string, date - `result` 'passed' | 'failed', required: Outcome of a screen performed under KYC/KYB reliance. - `verified_database_at` union: When you verified the business against a database source (ISO 8601). - string, date-time - string, date - `verified_govid_at` union: When you verified the business registration documents (ISO 8601). - string, date-time - string, date - `verified_proof_of_address_at` union: When you verified the business proof of address (ISO 8601), required for EEA customers and SEPA rails under reliance. - string, date-time - string, date ## Response `200` KYB status snapshot reflecting the submitted data. - KybStatusResponse: Full KYB status for an organization with a given provider. - `provider` 'bridge', required: KYC/KYB provider identifier. - `environment` 'production' | 'sandbox', required: Provider environment (production or sandbox). - `status` string, required: KYC/KYB status for the user. - `tos` KyxTosStatusDetail, required: Terms of Service acceptance status for a KYC or KYB flow. - `status` string, required: Status of Terms of Service acceptance. Passthrough from the provider. - `link` string, uri: ToS acceptance link, if pending. - `endorsements` KyxEndorsement[], required - `name` string, required: Endorsement identifier. - `status` string, required: Status of an endorsement. Passthrough from the provider. - `missing` string[], nullable, required: Missing requirements, or null if complete. - `issues` string[], nullable, required: Provider issue codes, or null if none. - `capabilities` KyxCapabilities, required: Capability statuses for the customer. - `payin_crypto` string, required: Status of a capability. Passthrough from the provider. - `payout_crypto` string, required: Status of a capability. Passthrough from the provider. - `payin_fiat` string, required: Status of a capability. Passthrough from the provider. - `payout_fiat` string, required: Status of a capability. Passthrough from the provider. - `requirements_due` string[], required: Top-level items still needed (e.g. link a bank account). - `future_requirements_due` string[], required: Items that will be required in the future. - `kyb` KyxVerificationStatusDetail, required: Verification status detail for a KYC or KYB check. - `status` string, required: Status of KYC/KYB verification. Passthrough from the provider. - `link` string, uri: Verification link, if applicable. - `rejection_reasons` string[]: Reasons for rejection, if status is closed or action_required. ## Changes - **2026-10-16** `4facbfa7f9d4`: 1 info - endpoint added [Operation history](https://skmtc.dev/privy-io/apis/privy-api/changes/v1/organizations/:organization_id/kyb/submit/post.md) --- [API](https://skmtc.dev/privy-io/apis/privy-api.md) - [All operations](https://skmtc.dev/privy-io/apis/privy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/privy-io/apis/privy-api/revisions/3a2288470053?raw)