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 investmentsINVESTED_WITH_CASH - User with investments and cash balanceINVESTED_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);
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: '[email protected]',
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);
Response example
{
"user": {
"_id": "64f0c51e7fb3fc001234abcd",
"email": "[email protected]",
"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
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.
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);
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: '[email protected]'
});
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();
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: '[email protected]',
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: '[email protected]',
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: '[email protected]',
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:
Troubleshooting
Error: 400 - Invalid email format
Solution: Ensure the email is a valid email address format (e.g., [email protected]).
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.
