Create New Accounts

After you’ve planned your account structure and configured your product, you’re ready to create your first customer account using XYB.

---

Prerequisites

Make sure you’ve completed:

• Product Configuration: Your account product must exist (with productId and version).

• Entity Creation: The customer entity (owner of the account) must be available.

• Authentication: You have access to XYB APIs via secure credentials.

---

Create Account via API

Endpoint

POST /api/v2.0/account

Sample Request Body

{
  "reference": "user-123",
  "name": "John Smith's Account",
  "productId": "f5e6a3aa-xxxx-yyyy-zzzz-abcdefghijkl",
  "productVersion": "1.0",
  "currency": "EUR",
  "owner": {
    "type": "INDIVIDUAL",
    "affiliation": "PERSONAL",
    "reference": "entity-xyz"
  },
  "tags": ["PREMIUM", "EU"],
  "attributes": {
    "risk_level": "LOW",
    "kyc_status": "VERIFIED"
  },
  "coordinates": {
    "banking": {
      "iban": "DE89370400440532013000"
    }
  }
}

Sample Response

{
  "id": "2f3a...fd91",
  "reference": "user-123",
  "name": "John Smith's Account",
  "status": "OPEN",
  "productUuid": "...",
  "wallets": [...],
  "owner": {...}
}

Error Codes

• 405 - Account already exists with this reference or coordinates

• 400 - Validation failure (missing or mismatched data)

Learn more about Account Management APIs.

---

---

Creating Accounts via UI

If you want to allow end-users or internal agents to trigger account creation via your own frontend:

1. Build a form to collect:

   • Owner reference

   • Account name

   • Currency

   • Product ID + version

   • Optional tags or attributes

2. Post the form data to your backend

3. Call the POST /account endpoint using backend service logic

4. Show success, redirect, or display the new account data

---

What Happens Behind the Scenes?

When you create an account:

• XYB validates product config and entity

• Creates account + default wallet(s)

• Links ledger account if configured

• Assigns banking coordinates (if provided)

• Publishes Kafka event account-created.You can subscribe to this event or query the account at any time. Learn more about the Accounts Kafka topics.