> ## Documentation Index > Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt > Use this file to discover all available pages before exploring further. # Create child org > Creates a new child organization under the caller's organization. The child org is created in an unapproved state; approval happens separately through the Etherfuse approval workflow. Create the org here first, then add wallets and bank accounts as separate steps with [Register customer wallet](/api-reference/wallets/register-customer-wallet) and [Create bank account](/api-reference/bank-accounts/create-bank-account-api). Handling each step on its own gives clearer error messages and lets you guide customers through any failures without re-sending everything. If the provided `id` collides with an existing record, the request returns 409. All fields are optional: sending an empty body `{}` creates a bare organization. ## Account types Every organization has an `accountType` of either `personal` (an individual customer completing KYC) or `business` (a company completing KYB). The two are handled differently downstream: personal orgs go through individual KYC and Plaid; business orgs go through KYB and skip per-wallet compliance. - `personal`: pass `userInfo` so the end user records are created and we can email them on status changes. - `business`: `userInfo` is rejected (business orgs do not have a single end user). `accountType` is currently optional and defaults to `personal`. **It will become required in a future release.** Start sending it explicitly now. ## Authenticating as the customer For a **personal** org, if the customer signs in with a JWT (see [JWT User Authentication](/guides/jwt-authentication)), pass the **same** id as the JWT `sub` here in `id`; the shared id ties the org to that user. A **business** org is different: it has its own id and isn't tied to one user, and `sub` identifies a person, so never reuse a customer's `sub`/id as a business org `id` (that returns 409). The people who run its KYB sign in with their own `sub` and select the business via `?org=` on launch. ## Business onboarding For a **business** org, pass `country` (ISO code) to generate the KYB onboarding at creation so the user drops straight into KYB; omit it and they're prompted for their country when they begin. `country` is rejected on personal orgs. Members are added separately: create the org first, then add the people who complete its KYB with [Add organization member](/api-reference/organizations/add-organization-member). ## OpenAPI ````yaml /openapi.json post /ramp/organization openapi: 3.1.0 info: title: Etherfuse FX API description: Partner-facing ramp API for onramps, offramps, swaps, and KYC. license: name: Proprietary version: 1.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Authentication description: >- Partner JWT authentication — exchange a JWT for an access token, or launch a user into the app. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Assets description: Rampable stablecoins and stablebonds available per blockchain. - name: Onboarding description: Hosted and programmatic customer onboarding. - name: Agreements description: Legal agreement acceptance during onboarding. - name: Bank Accounts description: Register and retrieve customer bank accounts. - name: Quotes description: Price quotes for onramps, offramps, and swaps. - name: Orders description: Create, track, and manage ramp orders. - name: Swaps description: Crypto-to-crypto swaps. - name: Sponsored description: Token approvals for sponsored (gasless) offramps. - name: Customers description: Customer (child-organization) records. - name: Wallets description: Register and manage customer wallets. - name: KYC description: Submit and check customer KYC status. - name: Webhooks description: Event notification subscriptions. - name: Organizations description: Organization identity, child orgs, and partner fees. paths: /ramp/organization: post: tags: - Organizations summary: Create child org description: >- Creates a new child organization under the caller's organization. The child org is created in an unapproved state; approval happens separately through the Etherfuse approval workflow. Create the org here first, then add wallets and bank accounts as separate steps with [Register customer wallet](/api-reference/wallets/register-customer-wallet) and [Create bank account](/api-reference/bank-accounts/create-bank-account-api). Handling each step on its own gives clearer error messages and lets you guide customers through any failures without re-sending everything. If the provided `id` collides with an existing record, the request returns 409. All fields are optional: sending an empty body `{}` creates a bare organization. ## Account types Every organization has an `accountType` of either `personal` (an individual customer completing KYC) or `business` (a company completing KYB). The two are handled differently downstream: personal orgs go through individual KYC and Plaid; business orgs go through KYB and skip per-wallet compliance. - `personal`: pass `userInfo` so the end user records are created and we can email them on status changes. - `business`: `userInfo` is rejected (business orgs do not have a single end user). `accountType` is currently optional and defaults to `personal`. **It will become required in a future release.** Start sending it explicitly now. ## Authenticating as the customer For a **personal** org, if the customer signs in with a JWT (see [JWT User Authentication](/guides/jwt-authentication)), pass the **same** id as the JWT `sub` here in `id`; the shared id ties the org to that user. A **business** org is different: it has its own id and isn't tied to one user, and `sub` identifies a person, so never reuse a customer's `sub`/id as a business org `id` (that returns 409). The people who run its KYB sign in with their own `sub` and select the business via `?org=` on launch. ## Business onboarding For a **business** org, pass `country` (ISO code) to generate the KYB onboarding at creation so the user drops straight into KYB; omit it and they're prompted for their country when they begin. `country` is rejected on personal orgs. Members are added separately: create the org first, then add the people who complete its KYB with [Add organization member](/api-reference/organizations/add-organization-member). operationId: create_child_organization requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateChildOrgRequest' required: true responses: '201': description: The created child organization content: application/json: schema: $ref: '#/components/schemas/CreateChildOrgResponse' '400': description: Invalid request '409': description: >- A provided UUID collides with an existing record, or the `id` already identifies a customer and `accountType` is `business` (a customer id cannot be reused as a business organization). components: schemas: CreateChildOrgRequest: type: object properties: accountType: type: - string - 'null' enum: - personal - business description: >- Whether this org is an individual or a company: - `personal`: an individual customer completing KYC. Pass `userInfo`. - `business`: a company completing KYB. `userInfo` is rejected. Optional today and defaults to `personal`, but it will become required in a future release once partners have migrated, so send it explicitly now. example: personal displayName: type: - string - 'null' description: >- The organization's name. For a `business` org, this is the company name. id: type: - string - 'null' format: uuid userInfo: oneOf: - type: 'null' - $ref: '#/components/schemas/UserInfo' description: >- Optional info about the end user. Required eventually for personal orgs. Rejected on business orgs (those don't have a single end user). country: type: - string - 'null' description: >- ISO 3166-1 alpha-2 country code (e.g. `MX`). Business orgs only; rejected on personal orgs. When provided, Etherfuse generates the KYB onboarding at creation, seeding the company entity with this country so the user lands straight in KYB. Omit it and the user is prompted for their country when they begin KYB. example: MX example: accountType: personal displayName: Ana García id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 userInfo: displayName: Ana García email: ana@example.com CreateChildOrgResponse: type: object required: - organizationId - displayName - accountType properties: accountType: type: string enum: - business - personal description: Account type of the child organization. example: business displayName: type: string organizationId: type: string format: uuid wallets: type: array items: $ref: '#/components/schemas/Wallet' description: >- Wallets registered during organization creation. Empty array omitted from response. bankAccount: oneOf: - $ref: '#/components/schemas/BankAccount' - type: 'null' description: >- Bank account created during organization creation, if one was provided in the request. Omitted when not present. example: organizationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 displayName: Acme Inc. accountType: business UserInfo: type: object description: >- Optional user info collected at org/customer creation time. When provided, the user record is pre-populated with the partner's known display name and email so the customer's eventual Firebase sign-in attaches to the correct user, and so we can send status-change emails. Will eventually be required. required: - email - displayName properties: displayName: type: string email: type: string Wallet: type: object required: - walletId - customerId - createdAt - updatedAt - publicKey - blockchain properties: blockchain: $ref: '#/components/schemas/Blockchain' description: Blockchain the wallet is on. claimedOwnership: type: - boolean - 'null' description: >- Whether the wallet has active claimed ownership by the organization. When `true` and the organization is approved, the wallet is treated as compliant without requiring individual KYC. Only present when claimed ownership has been set. createdAt: type: string format: date-time description: Timestamp when the wallet was created. customerId: type: string format: uuid description: ID of the customer who owns this wallet. deletedAt: type: - string - 'null' format: date-time description: Timestamp when the wallet was deleted (if applicable). displayName: type: - string - 'null' description: Display name for the wallet. kycOnChain: type: - boolean - 'null' description: >- Whether KYC is marked on-chain for the wallet. Only present for Solana wallets; for other blockchains this field is omitted as on-chain KYC marking does not apply. kycStatus: type: - string - 'null' description: >- Current KYC verification status for the wallet. Only present for individual wallet calls. The `approved_chain_deploying` status indicates the user is approved but waiting for on-chain marking (Solana only). publicKey: type: string description: Public key / address of the wallet. signerPublicKey: type: - string - 'null' description: >- For embedded (non-custodial) wallets, the compressed SEC1 P-256 public key of the owner key that authorizes transactions. Absent for bring-your-own wallets. updatedAt: type: string format: date-time description: Timestamp when the wallet was last updated. walletId: type: string format: uuid description: Unique identifier for the wallet. example: blockchain: stellar claimedOwnership: true createdAt: '2026-05-01T14:30:00Z' customerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 kycStatus: approved publicKey: GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL updatedAt: '2026-05-02T09:15:00Z' walletId: c3d4e5f6-a7b8-9012-cdef-123456789012 BankAccount: type: object required: - bankAccountId - customerId - createdAt - updatedAt - currency - abbrClabe - compliant - needsWork - status properties: abbrClabe: type: string description: Abbreviated CLABE number for the bank account. deprecated: true bankAccountId: type: string format: uuid description: Unique identifier for the bank account. Must be a valid UUID v4. compliant: type: boolean description: >- Whether the bank account is compliant and can be used for orders. A bank becomes compliant once the customer completes the required identity verification (or the owning organization is approved). **While `false`, the customer must complete additional verification before the bank can be used** — launch them into the Identity verification flow (`scope: verification`, `target: /idv`); see [User launch flows](/guides/user-launch-flows#identity-verification). createdAt: type: string format: date-time description: Timestamp when the bank account was created. currency: type: string description: Settlement currency (ISO 4217, e.g. `MXN`). customerId: type: string format: uuid description: ID of the customer who owns this bank account. deletedAt: type: - string - 'null' format: date-time description: Timestamp when the bank account was deleted (if applicable). etherfuseDepositClabe: type: - string - 'null' description: Etherfuse deposit CLABE number. label: type: - string - 'null' description: Custom label for the bank account. needsWork: type: boolean description: >- Whether the bank account still needs work (e.g. failed verification) before it can be used for transactions. status: type: string description: Current status of the bank account. updatedAt: type: string format: date-time description: Timestamp when the bank account was last updated. example: abbrClabe: •••• 0004 bankAccountId: b2c3d4e5-f6a7-8901-bcde-f12345678901 compliant: true createdAt: '2026-05-01T14:30:00Z' currency: MXN customerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 etherfuseDepositClabe: '646180157000000004' label: Ana's SPEI account needsWork: false status: active updatedAt: '2026-05-02T09:15:00Z' Blockchain: type: string description: |- Canonical blockchain enum for API serialization. Use this type for JSON APIs and WebSocket messages. For database storage, convert to `BlockchainType`. enum: - stellar - solana - base - polygon - monad securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header. ````