> ## 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.
# Generate onboarding URL
> Generates a presigned URL for customer onboarding. If the customer does not exist, it
will be created. You generate a UUID for `customerId` and `bankAccountId`, and Etherfuse creates the
customer and bank account records associated with your organization.
**Deprecated. Sunset August 16, 2026.** Customer onboarding has consolidated onto a
single hosted flow: create the customer's `personal` organization with
`POST /ramp/organization`, then launch them into `/idv`, which runs identity
verification **and** agreement signing in one step. See
[Customer Onboarding (KYC)](/guides/onboarding). Migrate before the sunset date.
Upon visiting the URL, the customer has 15 minutes to complete onboarding (KYC
verification and bank account linking).
## Personal organizations only
This endpoint always creates a **personal** organization; it forces individual KYC.
There is no `accountType` field; pass `business` orgs through
`POST /ramp/organization` instead.
## userInfo
Pass `userInfo` with the end user's email and display name. When provided, Etherfuse
pre-creates the user record so the customer's eventual sign-in attaches to the right
user and we can email them on status changes (KYC approved/rejected, bank account
verified, etc.). `userInfo` is **required**, and neither `email` nor `displayName` may be blank. The
email is the address the customer confirms during verification and the only place it
comes from, so a customer created without one can never start KYC.
## Authenticating as the customer
If the customer signs in with a JWT (see [JWT User Authentication](/guides/jwt-authentication)), use the **same** value for `customerId` as the JWT `sub`. The shared id links the customer record to the user who signs in.
## OpenAPI
````yaml /openapi.json post /ramp/onboarding-url
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: 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 a customer's verification data, documents and questionnaire
answers, import a verification they already passed elsewhere, and check
where their KYC stands.
- name: Webhooks
description: Event notification subscriptions.
- name: Organizations
description: Organization identity, child orgs, and partner fees.
- name: Statements
description: >-
Monthly revenue share statements for closed months, as a list or as a CSV
or PDF download.
- name: Deprecated
description: >-
Endpoints kept working until their sunset date and then removed. See the
deprecations page for replacements and dates.
paths:
/ramp/onboarding-url:
post:
tags:
- Deprecated
summary: Generate onboarding URL
description: >-
Generates a presigned URL for customer onboarding. If the customer does
not exist, it
will be created. You generate a UUID for `customerId` and
`bankAccountId`, and Etherfuse creates the
customer and bank account records associated with your organization.
**Deprecated. Sunset August 16, 2026.** Customer onboarding has
consolidated onto a
single hosted flow: create the customer's `personal` organization with
`POST /ramp/organization`, then launch them into `/idv`, which runs
identity
verification **and** agreement signing in one step. See
[Customer Onboarding (KYC)](/guides/onboarding). Migrate before the
sunset date.
Upon visiting the URL, the customer has 15 minutes to complete
onboarding (KYC
verification and bank account linking).
## Personal organizations only
This endpoint always creates a **personal** organization; it forces
individual KYC.
There is no `accountType` field; pass `business` orgs through
`POST /ramp/organization` instead.
## userInfo
Pass `userInfo` with the end user's email and display name. When
provided, Etherfuse
pre-creates the user record so the customer's eventual sign-in attaches
to the right
user and we can email them on status changes (KYC approved/rejected,
bank account
verified, etc.). `userInfo` is **required**, and neither `email` nor
`displayName` may be blank. The
email is the address the customer confirms during verification and the
only place it
comes from, so a customer created without one can never start KYC.
## Authenticating as the customer
If the customer signs in with a JWT (see [JWT User
Authentication](/guides/jwt-authentication)), use the **same** value for
`customerId` as the JWT `sub`. The shared id links the customer record
to the user who signs in.
operationId: generate_onboarding_url
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateOnboardingUrlPayload'
required: true
responses:
'200':
description: A presigned onboarding URL
content:
application/json:
schema: {}
example:
presigned_url: >-
https://api.sand.etherfuse.com/onboarding?org_id=a1b2c3d4-...&customer_id=a1b2c3d4-...&expires=1748345400&signature=...
'400':
description: Invalid request
'409':
description: >-
The `publicKey` is already attached to another customer of your
organization. The body names the existing customer id. On retries,
reuse the same `customerId` (the call is idempotent for a customer
you own) instead of generating a new one.
content:
text/plain:
schema:
type: string
example: >-
You have already added user with this address, see org:
b45a5a15-3e4b-4e92-9167-635dd7e95252
deprecated: true
components:
schemas:
GenerateOnboardingUrlPayload:
type: object
required:
- customerId
- bankAccountId
- publicKey
- blockchain
- userInfo
properties:
bankAccountId:
type: string
format: uuid
blockchain:
$ref: '#/components/schemas/Blockchain'
customerId:
type: string
format: uuid
publicKey:
type: string
uiOverride:
type:
- string
- 'null'
userInfo:
$ref: '#/components/schemas/UserInfo'
description: >-
Info about the end user. Both fields are required and neither may be
blank. `email` is the address the customer confirms during
verification
and the only place it comes from, so a customer created without one
can
never start KYC. `displayName` is how the customer is addressed in
notices.
example:
bankAccountId: b2c3d4e5-f6a7-8901-bcde-f12345678901
blockchain: stellar
customerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
publicKey: GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL
userInfo:
displayName: Ana García
email: ana@example.com
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
UserInfo:
type: object
description: >-
Info about the end user, collected at org/customer creation time. The
user record is pre-populated with the partner's display name and email
so
the customer's eventual Firebase sign-in attaches to the correct user,
so
we can send status-change emails, and so identity verification has an
address to confirm.
required:
- email
- displayName
properties:
displayName:
type: string
email:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key sent in the Authorization header.
````