Create child org

curl --request POST \
  --url https://api.sand.etherfuse.com/ramp/organization \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountType": "personal",
  "displayName": "Ana García",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userInfo": {
    "displayName": "Ana García",
    "email": "[email protected]"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountType: 'personal',
    displayName: 'Ana García',
    id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    userInfo: {displayName: 'Ana García', email: '[email protected]'}
  })
};

fetch('https://api.sand.etherfuse.com/ramp/organization', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sand.etherfuse.com/ramp/organization"

payload = {
    "accountType": "personal",
    "displayName": "Ana García",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userInfo": {
        "displayName": "Ana García",
        "email": "[email protected]"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "displayName": "Acme Inc.",
  "accountType": "business"
}

Organizations

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 and Create bank account. 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), 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=<id> 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.

POST

ramp

organization

Create child org

curl --request POST \
  --url https://api.sand.etherfuse.com/ramp/organization \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountType": "personal",
  "displayName": "Ana García",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userInfo": {
    "displayName": "Ana García",
    "email": "[email protected]"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountType: 'personal',
    displayName: 'Ana García',
    id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    userInfo: {displayName: 'Ana García', email: '[email protected]'}
  })
};

fetch('https://api.sand.etherfuse.com/ramp/organization', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sand.etherfuse.com/ramp/organization"

payload = {
    "accountType": "personal",
    "displayName": "Ana García",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userInfo": {
        "displayName": "Ana García",
        "email": "[email protected]"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "displayName": "Acme Inc.",
  "accountType": "business"
}

Authorizations

Authorization

string

header

required

API key sent in the Authorization header.

Body

application/json

accountType

enum<string> | null

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.

Available options:

personal,

business

Example:

"personal"

displayName

string | null

The organization's display name: the friendly label shown in UIs and API responses. For a business org completing KYB, the legal entity name is captured separately via legalName.

string<uuid> | null

userInfo

null | object

Optional info about the end user. Required eventually for personal orgs. Rejected on business orgs (those don't have a single end user).

Show child attributes

country

string | null

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"

legalName

string | null

Legal entity name for the KYB company entity (e.g. the incorporated name on the company's registry documents). Pass it together with country when generating the KYB onboarding at creation; rejected without country. Independent of displayName: renaming the org does not change the legal name, and vice versa.

Example:

"Acme Corporation S.A. de C.V."

Response

The created child organization

accountType

enum<string>

required

Account type of the child organization.

Available options:

business,

personal

Example:

"business"

displayName

string

required

organizationId

string<uuid>

required

wallets

object[]

Wallets registered during organization creation. Empty array omitted from response.

Show child attributes

bankAccount

object | null

Bank account created during organization creation, if one was provided in the request. Omitted when not present.

Show child attributes

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"
}

Get organization Add organization member

⌘I

User Authentication

Ramp API

Lookup API

Create child org

Account types

Authenticating as the customer

Business onboarding

Authorizations

Body

Response