User builder flow

Overview

This guide walks you through creating test users in sandbox environments. Use these test endpoints to quickly set up users in various lifecycle states for testing different scenarios.

Test endpoints are only available in development and staging environments. They are disabled in production for security reasons. Always use the sandbox environment (api.sandbox.wealthyhood.com) when working with test endpoints.

All endpoints require an M2M bearer token. Test endpoints do not require the x-user-id header since they operate on test data.

Prerequisites

API access and M2M credentials
Sandbox environment access (development or staging)
Understanding of user lifecycle states

1) Discover available user statuses

Before creating test users, retrieve the list of available user statuses to understand what test scenarios you can set up. Available statuses for B2B test user creation:

INVESTED - User with investments
INVESTED_WITH_CASH - User with investments and cash balance
INVESTED_WITH_SAVINGS - User with investments and savings

Only these three statuses are available for B2B test user creation. All users created via this endpoint will have investments, and optionally cash or savings. Use GET /test/help/statuses to get all valid status values:

const BASE = 'https://api.sandbox.wealthyhood.com';

async function getAvailableStatuses({ token }) {
  const res = await fetch(`${BASE}/test/help/statuses`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Accept': 'application/json'
    }
  });
  if (!res.ok) throw new Error(`Failed to get statuses: ${res.status}`);
  const { statuses } = await res.json();
  return statuses;
}

// Get all available statuses
const statuses = await getAvailableStatuses({ token: 'YOUR_M2M_TOKEN' });
console.log('Available statuses:', statuses);

curl -X GET 'https://api.sandbox.wealthyhood.com/test/help/statuses' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN'

2) Create a test user

Create a test user with a specific status. This sets up a user account in the desired lifecycle state with all associated data (accounts, addresses, KYC operations, portfolios, etc.). Use POST /test/users to create a test user:

async function createTestUser({ token, email, status }) {
  const res = await fetch(`${BASE}/test/users`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({ email, status })
  });
  if (!res.ok) {
    const error = await res.json();
    throw new Error(`Failed to create user: ${error.message || res.status}`);
  }
  const { user } = await res.json();
  return user;
}

// Example: Create an invested user with cash
const user = await createTestUser({
  token: 'YOUR_M2M_TOKEN',
  email: 'test.user@example.com',
  status: 'INVESTED_WITH_CASH'
});

console.log('Created user ID:', user._id);
console.log('User status:', user.status);
console.log('Has portfolio:', user.portfolios?.length > 0);

curl -X POST 'https://api.sandbox.wealthyhood.com/test/users' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -d '{
    "email": "test.user@example.com",
    "status": "INVESTED_WITH_CASH"
  }'

Response example

{
  "user": {
    "_id": "64f0c51e7fb3fc001234abcd",
    "email": "test.user@example.com",
    "status": "INVESTED_WITH_CASH",
    "currency": "EUR",
    "portfolios": [...]
  }
}

The response includes the created user object with populated portfolios:

portfolios - User portfolios

Save the id field for use in subsequent requests.

Request parameters

string

required

Email address for the test user. Must be a valid email format. Use unique emails (e.g., include a timestamp) to avoid conflicts when running tests multiple times.

string

required

User status from the available statuses. Determines what data and relationships are created with the user (e.g., portfolios, cash balances).

3) Verify user creation

Verify that the user was created successfully and check their details:

// The user object returned from createTestUser already contains all details
console.log('User ID:', user._id);
console.log('Email:', user.email);
console.log('Status:', user.status);
console.log('Currency:', user.currency);
console.log('Portfolios:', user.portfolios?.length || 0);

# The response from POST /test/users already contains all user details
# No additional request needed

4) Clean up test users (optional)

After completing your tests, clean up test users to keep your sandbox environment organized. Use DELETE /test/users to delete a test user:

async function deleteTestUser({ token, email }) {
  const res = await fetch(`${BASE}/test/users`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({ email })
  });
  if (!res.ok) throw new Error(`Failed to delete user: ${res.status}`);
  return res.ok;
}

// Clean up test user
await deleteTestUser({
  token: 'YOUR_M2M_TOKEN',
  email: 'test.user@example.com'
});

curl -X DELETE 'https://api.sandbox.wealthyhood.com/test/users' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -d '{
    "email": "test.user@example.com"
  }'

Response example

HTTP/1.1 200 OK
(No response body)

Use this endpoint to clean up test users after completing your test scenarios to keep your sandbox environment tidy.

Complete example

Here’s a complete example that discovers statuses, creates a test user, and verifies the creation:

const BASE = 'https://api.sandbox.wealthyhood.com';
const token = 'YOUR_M2M_TOKEN';

async function createSandboxUserFlow() {
  try {
    // 1. Get available statuses
    const statusesRes = await fetch(`${BASE}/test/help/statuses`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
      }
    });
    const { statuses } = await statusesRes.json();
    console.log('Available statuses:', statuses);

    // 2. Create test user
    const userRes = await fetch(`${BASE}/test/users`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        email: `test-${Date.now()}@example.com`,
        status: 'INVESTED_WITH_CASH'
      })
    });
    const { user } = await userRes.json();
    console.log('Created user:', user._id);
    console.log('User status:', user.status);
    console.log('Portfolios:', user.portfolios?.length || 0);

    return user;
  } catch (error) {
    console.error('Error creating sandbox user:', error);
    throw error;
  }
}

createSandboxUserFlow();

#!/bin/bash

BASE="https://api.sandbox.wealthyhood.com"
TOKEN="YOUR_M2M_TOKEN"
EMAIL="test-$(date +%s)@example.com"

# 1. Get available statuses
echo "Fetching available statuses..."
STATUSES_RESPONSE=$(curl -s -X GET "${BASE}/test/help/statuses" \
  -H "Authorization: Bearer ${TOKEN}")

echo "Available statuses:"
echo $STATUSES_RESPONSE | jq '.statuses'

# 2. Create test user
echo "Creating test user..."
USER_RESPONSE=$(curl -s -X POST "${BASE}/test/users" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"email\": \"${EMAIL}\", \"status\": \"INVESTED_WITH_CASH\"}")

USER_ID=$(echo $USER_RESPONSE | jq -r '.user._id')
echo "Created user: ${USER_ID}"
echo "User details:"
echo $USER_RESPONSE | jq '.user | {_id, email, status, currency}'

Common use cases

Creating users for investment testing

Create users with investments for testing investment orders:

// Create user with investments
const investor = await createTestUser({
  token,
  email: 'investor@example.com',
  status: 'INVESTED'
});

// User now has:
// - Portfolio with investments
// - Ready for investment order testing

Creating users with cash for deposit testing

Create users with investments and cash for testing deposits and cash operations:

// Create user with investments and cash
const userWithCash = await createTestUser({
  token,
  email: 'cash@example.com',
  status: 'INVESTED_WITH_CASH'
});

// User now has:
// - Portfolio with investments
// - Cash balance
// - Ready for deposit and withdrawal testing

Creating users with savings

Create users with investments and savings for testing savings-related features:

// Create user with investments and savings
const userWithSavings = await createTestUser({
  token,
  email: 'savings@example.com',
  status: 'INVESTED_WITH_SAVINGS'
});

// User now has:
// - Portfolio with investments
// - Savings account
// - Ready for savings order testing

Next steps

After creating a sandbox user, you can:

Add deposits - Use the Sandbox payments flow to simulate deposits
Test investment orders - Submit orders using the Order execution flow
Test withdrawals - Create withdrawals using the Cash movements flow
Test savings orders - Use the Savings orders flow

Troubleshooting

Invalid email format

Error: 400 - Invalid email format Solution: Ensure the email is a valid email address format (e.g., user@example.com).

Invalid status

Error: 400 - Invalid status or Status must be one of: INVESTED, INVESTED_WITH_CASH, INVESTED_WITH_SAVINGS Solution: Only three statuses are allowed for B2B test user creation: INVESTED, INVESTED_WITH_CASH, and INVESTED_WITH_SAVINGS. Use GET /test/help/statuses to retrieve the list of valid status values. Ensure the status string matches exactly (case-sensitive).

User already exists

Error: 400 - User already exists or similar Solution: Use unique email addresses for each test user. Include a timestamp or UUID in the email (e.g., test-${Date.now()}@example.com).

Endpoint not available

Error: 403 - Forbidden or endpoint returns 404 Solution: Verify you’re using the sandbox environment (api.sandbox.wealthyhood.com). Test endpoints are disabled in production.

Always use unique email addresses for test users to avoid conflicts. Consider including timestamps or UUIDs in email addresses when running tests multiple times.

Getting started

Screens

Flows

Sandbox Flows

Overview

Prerequisites

1) Discover available user statuses

2) Create a test user

Response example

Request parameters

3) Verify user creation

4) Clean up test users (optional)

Response example

Complete example

Common use cases

Creating users for investment testing

Creating users with cash for deposit testing

Creating users with savings

Next steps

Troubleshooting

Invalid email format

Invalid status

User already exists

Endpoint not available

​Overview

​Prerequisites

​1) Discover available user statuses

​2) Create a test user

​Response example

​Request parameters

​3) Verify user creation

​4) Clean up test users (optional)

​Response example

​Complete example

​Common use cases

​Creating users for investment testing

​Creating users with cash for deposit testing

​Creating users with savings

​Next steps

​Troubleshooting

​Invalid email format

​Invalid status

​User already exists

​Endpoint not available

Overview

Prerequisites

1) Discover available user statuses

2) Create a test user

Response example

Request parameters

3) Verify user creation

4) Clean up test users (optional)

Response example

Complete example

Common use cases

Creating users for investment testing

Creating users with cash for deposit testing

Creating users with savings

Next steps

Troubleshooting

Invalid email format

Invalid status

User already exists

Endpoint not available