> ## Documentation Index > Fetch the complete documentation index at: https://docs.zbx.boomfi.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Create Sub-Merchant > Onboard a merchant under your partner account. If KYC is required, the response includes kyc_next_action with a one-time verification URL; accounts are provisioned after KYC approval. To reuse an existing Sumsub KYC, send share_token with kyc_questionnaire; no verification URL is returned. Reusing the same external_reference returns the existing org and ignores share_token. ## OpenAPI ````yaml /openapi.yaml post /partners/orgs openapi: 3.1.0 info: contact: email: support@boomfi.xyz name: API Support description: >- The BoomFi Merchants API provides a set of endpoints for merchants to manage their accounts, transactions, and more. Hosts differ per brand/environment; use the brand-specific base URL from the docs. title: ZBX Merchants API version: '1.0' servers: - url: https://mapi.zbx.com/v1 description: Production security: [] tags: - description: Payment links name: Paylinks - description: Billing plans name: Plans - description: Subscriptions name: Subscriptions - description: Customer records name: Customers - description: Invoices name: Invoices - description: Payments name: Payments - description: Organisation events name: Events - description: Organisation profile and display settings name: Organisation - description: Webhook and request-signing secrets name: Secrets - description: Settlement accounts name: Accounts - name: External Accounts - description: Managed virtual accounts, balances, pay-in, and payout name: Virtual Accounts - description: Partner-managed accounts, virtual accounts, pay-in, and payout name: Partners - description: Partner maintain-balance automations name: Partner Balance Monitoring - description: Tradeable currencies, instruments, and swap targets name: Instruments - description: RFQ quotes name: Quotes - description: RFQ orders and one-click trades name: Orders - description: Executed trades name: Trades paths: /partners/orgs: post: tags: - Partners summary: Create Sub-Merchant description: >- Onboard a merchant under your partner account. If KYC is required, the response includes kyc_next_action with a one-time verification URL; accounts are provisioned after KYC approval. To reuse an existing Sumsub KYC, send share_token with kyc_questionnaire; no verification URL is returned. Reusing the same external_reference returns the existing org and ignores share_token. requestBody: content: application/json: schema: $ref: '#/components/schemas/onboarding.CreateZBXOrgRequest' description: Merchant to onboard required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/partners.SubMerchantResponse' '201': description: Created content: application/json: schema: $ref: '#/components/schemas/partners.SubMerchantResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '424': description: Failed Dependency content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' security: - ApiKeyAuth: [] ApiNonce: [] ApiSignature: [] components: schemas: onboarding.CreateZBXOrgRequest: properties: address: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgAddress' description: Postal address. Country and city are required when present. country_of_incorporation: description: alpha-3 type: string dba_name: description: Dba name for this resource. type: string end_user_ip: description: >- Merchant IP address at signup, used for risk assessment. Optional. If omitted, the connecting server address is used, which is usually a datacenter IP. type: string external_reference: description: External reference for this resource. type: string kyc_questionnaire: allOf: - $ref: '#/components/schemas/onboarding.ZBXKYCQuestionnaire' description: >- Answers to ZBX's CDD questionnaire. Required with share_token, and only accepted with it. legal_name: description: >- Legal name used to match inbound bank transfers to this merchant. Falls back to name when omitted. type: string mcc: allOf: - $ref: '#/components/schemas/onboarding.OrgMCC' description: >- Mcc for this resource. Optional, but all three sub-fields are required when it is present — a half-filled MCC is a mistake, an absent one is a choice. mid: description: Mid for this resource. type: string name: description: Display name. type: string owner: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgOwnerRequest' description: >- Owner for this resource. owner.phone must be a verified E.164 mobile. partner_id: description: >- Identifier of the partner organisation, when this org is under a partner. type: string payment_fee_pct: description: Payment fee percentage. type: number principal_place_of_business: description: alpha-3 country code type: string registration_number: description: Registration number for this resource. type: string settlement_accounts: description: >- Accounts exists only to be rejected, and is untyped so that any shape gets the explanation below rather than a binding error about a missing sub-field. items: {} type: array share_token: description: >- Sumsub share token from your own Sumsub account, generated for ZBX's Sumsub client id. It imports the merchant's KYC so they do not upload documents again. Requires kyc_questionnaire, and is used once, when the org is created. type: string webhook_url: description: HTTPS URL that receives webhook events. type: string required: - external_reference - name - owner type: object partners.SubMerchantResponse: properties: data: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgResponse' description: The merchant organisation. error: description: True when the request failed. type: boolean message: description: Human-readable status or error message. type: string type: object internal.ErrorResponse: properties: error: allOf: - $ref: '#/components/schemas/internal.ErrorStruct' description: Error details including HTTP-style code and message. type: object onboarding.CreateOrgAddress: properties: building_number: description: Building number for this resource. type: string city: description: City for the postal address. type: string country: description: ISO 3166-1 alpha-2 country code. type: string flat_number: description: Flat number for this resource. type: string postal_code: description: Postal or ZIP code. type: string state: description: State, province, or region. type: string street: description: Street for this resource. type: string required: - city - country type: object onboarding.ZBXKYCQuestionnaire: properties: acting_capacity: description: >- Acting capacity: 156 own behalf, 157 agent or on behalf of another person (ZBX reviews these manually). enum: - '156' - '157' example: '156' type: string annual_income: description: >- Annual gross income in EUR: 74 up to 10,000; 75 10,000-50,000; 76 50,000-300,000; 77 more than 300,000. enum: - '74' - '75' - '76' - '77' example: '75' type: string employment_jurisdiction: description: >- Country of employment, ISO 3166-1 alpha-2, or N/A. Optional only when employment_type_or_status is 17. example: MT type: string employment_type_or_status: description: >- Employment status: 15 employed, 16 self-employed or business owner, 17 unemployed, 18 retired, 19 student, carer or on benefits. enum: - '15' - '16' - '17' - '18' - '19' example: '16' type: string expected_deposit_one_year: description: >- Expected deposits over one year in EUR: 83 up to 10,000; 84 10,000-150,000; 85 more than 150,000. enum: - '83' - '84' - '85' example: '83' type: string hnwi_str: description: >- Approximate net worth in EUR: 78 under 100,000; 79 100,000-1,000,000; 80 1,000,000 or more. enum: - '78' - '79' - '80' example: '79' type: string industry: description: >- Industry: option id 20-52, or 53 (other) with optional free text as 53:, up to 100 characters. example: '51' type: string investment_citizenship: description: 'Investor immigration programme (golden visa): 81 yes, 82 no.' enum: - '81' - '82' example: '82' type: string sdd_country_select: description: Country of residence, ISO 3166-1 alpha-2. example: MT type: string source_of_funds: description: >- Source of funds: comma-separated option ids 54-70, 72 or 73. 71 (third-party funding) is not accepted here. example: 66,70 type: string source_of_funds_of_country: description: Countries the funds come from, comma-separated ISO 3166-1 alpha-2. example: MT,DE type: string source_of_wealth_of_country: description: >- Countries the wealth was accumulated in, comma-separated ISO 3166-1 alpha-2. example: MT type: string type: object onboarding.OrgMCC: properties: code: description: Machine-readable code (error, MCC, or reason code). type: string description: description: Human-readable description. type: string risk_tier: description: Risk tier for this resource. type: string required: - code - description - risk_tier type: object onboarding.CreateOrgOwnerRequest: properties: email: description: Email address. type: string name: description: Display name. type: string phone: description: Phone number. type: string required: - email - name type: object onboarding.CreateOrgResponse: properties: created_at: description: When the resource was created (RFC3339). type: string kyc_next_action: description: >- Next step while kyc_status is "pending": "kyc_required:" (a one-time verification url), "tin_required" or "edd_required". type: string kyc_status: description: >- Merchant KYC state with the custody provider: "pending", "accepted" or "rejected". Empty in self-custody environments. type: string name: description: Display name. type: string org_id: description: Organisation ID that owns this resource. type: string owner: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgOwnerResponse' description: Owner for this resource. partner_id: description: >- Identifier of the partner organisation, when this org is under a partner. type: string settlement_accounts: description: Settlement accounts for this resource. items: $ref: '#/components/schemas/onboarding.CreateOrgAccountResponse' type: array type: object internal.ErrorStruct: properties: code: description: |- Error code Example: 400 example: 400 type: integer errors: description: List of errors items: $ref: '#/components/schemas/internal.SingleError' type: array message: description: |- Error message Example: Insufficient quantity example: Insufficient quantity type: string type: object onboarding.CreateOrgOwnerResponse: properties: email: description: Email address. type: string name: description: Display name. type: string phone: description: Phone number. type: string user_id: description: Identifier of the user associated with this resource. type: string type: object onboarding.CreateOrgAccountResponse: properties: account_number: description: Bank account number (IBAN), set only for a fiat account. type: string address: description: >- On-chain wallet address. Empty for a fiat account — see account_number. type: string bank: allOf: - $ref: '#/components/schemas/onboarding.BankDetails' description: |- Bank details for a fiat account. Nil until the custody provider has delivered them (e.g. while the account is still Pending). chain_id: description: Blockchain chain ID. type: integer currencies: description: Supported currency codes for this account or chain. items: type: string type: array id: description: Unique resource identifier. type: integer name: description: Display name. type: string reference: description: Merchant-defined reference string. type: string type: object internal.SingleError: properties: domain: description: |- Domain Example: orders example: orders type: string reason: description: |- Error Reason Example: InsufficientQuantity example: InsufficientQuantity type: string type: object onboarding.BankDetails: properties: account_holder_name: description: |- Name the account is held under. Verify this matches before wiring — most banks check it against the IBAN. type: string address: description: Bank's registered address. type: string bic: description: Bank Identifier Code / SWIFT code. type: string country: description: Bank's country, ISO 3166-1 alpha-2. type: string name: description: Bank name. type: string type: object securitySchemes: ApiKeyAuth: in: header name: X-API-KEY type: apiKey ApiNonce: in: header name: X-API-Nonce type: apiKey ApiSignature: in: header name: X-API-Signature type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.