Data Export - Wealthyhood API Docs

This documentation describes the data export format for loading into your data platform. The export includes portfolio snapshots and all financial activities for each export date.

Overview

The data export provides a comprehensive snapshot of user portfolios and financial activity for a configurable time window. This data is designed for data platform integration and enables you to:

Track portfolio valuations over time
Analyse user financial activity patterns
Generate reports and analytics
Build dashboards and visualizations

Export API

Use the Data Exports API to initiate and monitor export runs:

Create a run — POST /b2b/data-exports with an optional activity window
Poll for completion — GET /b2b/data-exports/{id} until status is Completed
Download the file — fetch the JSON from the fileUri in the completed run response

The run response includes activityFrom and activityTo reflecting the resolved activity window for that export.

Activity window options

Incremental export (default)

Send an empty request body to export activity since the latest completed run’s activityTo through the new run’s initiation time. On the first export, no lower bound is applied.

{}

Custom activity range

Pass both activityFrom and activityTo to backfill or re-export a specific period.

{
  "activityFrom": "2025-01-01T00:00:00.000Z",
  "activityTo": "2025-01-31T23:59:59.999Z"
}

Validation rules:

Both fields are required when specifying a custom window (providing only one returns 400)
activityFrom must be before activityTo
activityTo cannot be in the future
The range cannot exceed 90 days

Only one active run (Pending or InProgress) is allowed at a time. A concurrent create request returns 409 with the existing run.

Export Structure

Each export contains three main sections:

{
  "metadata": { ... },
  "snapshots": [ ... ],
  "activity": { ... }
}

Metadata

The metadata section contains export timing and version information:

initiatedAt: When the export process started (ISO 8601 timestamp)
exportedAt: When the export was completed (ISO 8601 timestamp)
schemaVersion: Schema version for compatibility tracking (semantic versioning)
activityFrom: Lower bound (exclusive) for activity included in this export, when applicable
activityTo: Upper bound (inclusive) for activity included in this export

Snapshots

The snapshots array contains end-of-day portfolio state for each user. Each snapshot includes:

User identification: userId and email
Valuation: Portfolio components (cash, savings, holdings, total) with values and currencies
Portfolio: Individual asset holdings with quantities, prices, and performance metrics

Activity

The activity section contains financial activity within the export window, organized by type:

Transactions, investment/savings orders, and automations: Filtered to the export activity window
Bank accounts: Current state reference data (not filtered by the activity window)

Activity types included:

Transactions: All transaction activities (investments, deposits, withdrawals, savings)
Investment Orders: Buy/sell orders for investment assets
Savings Orders: Top-ups and withdrawals for savings products
Automations: Recurring investment, savings, and rebalance automations updated in the activity window
Bank Accounts: Full snapshot of the partner’s current bank accounts (not filtered by the activity window)

Data Model

Snapshot Structure

Each snapshot represents a user’s portfolio state at end-of-day:

User Information

Each snapshot includes minimal user identification:

userId: Unique user identifier
email: User’s email address

Valuation Components

The valuation object contains four portfolio components:

cash: Available cash balance (value + currency)
savings: Money Market Funds balance with interest details (value + currency + unrealisedMonthlyInterest)
holdings: Investment holdings value with daily performance (value + currency + upBy/downBy)
total: Total portfolio value with daily performance (value + currency + upBy/downBy)

All values are in euros (major currency units), not cents.

Portfolio Holdings

The portfolio array contains individual asset holdings:

assetId: Asset identifier (e.g., ‘equities_apple’, ‘etf_vwce’)
isin: International Securities Identification Number
quantity: Number of shares/units held
latestPrice: Price per unit (amount + currency)
holdingWeightPercentage: Percentage weight in portfolio
dailyReturnPercentage: Daily return percentage for the asset

Activity Structure

All activity items include an owner field (user identifier) to link them to users in snapshots.

Transactions

Transaction activities represent all financial movements:Activity Types:

Investment: Buy, Sell, Rebalance, Dividends
Cash: Deposit, Withdraw
Savings: CashToSavings, SavingsToCash, SavingsInterest

Fields:

owner: User identifier
activityType: Type of activity
createdAt, updatedAt: Timestamps
status: Transaction status
currency: ISO 4217 currency code
amount: User-facing amount in euros (for investment transactions, matches getDisplayAmount; for deposits, withdrawals, and savings, matches stored consideration)
bankAccount: Bank account ID (only for Deposit/Withdraw)
details.orders[].consideration.amount: User-facing order amount (same rules as investment orders)

Investment Orders

Investment orders represent buy/sell orders for investment assets:Fields:

id, owner, transactionId
isin, assetId: Asset identification
side: Buy or Sell
status: Pending, Matched, Rejected, Settled, Cancelled
quantity: Number of shares/units
consideration: User-facing amount (getDisplayAmount) in euros
fees (optional, matched/settled orders only): Persisted Wealthyhood fee breakdown — fx from displayFxFee, commission from fees.commission
partnerFees (optional, matched/settled orders only): Persisted partner countervalue breakdown — fx from displayPartnerFxFee, commission from partnerFees.commission
unitPrice: Price per unit at settlement
exchangeRate: Exchange rate used (if applicable)
createdAt, updatedAt, filledAt, marketSettledAt: Timestamps

Savings Orders

Savings orders represent top-ups and withdrawals for savings products:Fields:

id, owner
side: “Buy” (top-up) or “Sell” (withdrawal)
status: Pending, Matched, Rejected, Settled, Cancelled
currency: ISO 4217 currency code
amount: Amount in euros
savingsProductId: Savings product identifier (e.g., ‘mmf_dist_eur’)
createdAt, updatedAt, settledAt: Timestamps

Automations

Automations represent recurring investments, savings top-ups, or monthly rebalancing. An automation is included when its updatedAt or its linked mandate’s updatedAt falls in (activityFrom, activityTo]. The first export (no activityFrom) applies only the upper bound. Inactive and cancelled automations are included when they match the window so you can upsert by id. updatedAt on the item is always the automation document timestamp — a mandate-only change can include a row whose updatedAt is before activityFrom, but automations updated after activityTo are deferred to the next export.Fields:

id, owner
category: TopUpAutomation, SavingsTopUpAutomation, or RebalanceAutomation
status: Active, Inactive, Pending
frequency: Monthly (currently only option)
dayOfMonth: Day of month for execution (top-up and savings only)
currency, amount: Recurring amount (top-up and savings only)
allocationMethod: holdings allocation (for TopUpAutomation)
savingsProduct: Savings product (for SavingsTopUpAutomation)
mandate: Direct debit mandate details (top-up and savings only)
createdAt, updatedAt: Timestamps

Bank Accounts

Each export includes a full snapshot of the partner’s current bank accounts. Bank accounts are not filtered by the activity window.Fields:

id, owner
accountName: Account label/name
accountNumber: IBAN format account number
bankName: Bank name (optional)
holderName: Account holder name (optional)
status: PendingVerification, Active, Disabled
createdAt, updatedAt: Timestamps

Data Formats

Amounts

All monetary amounts are stored in euros (major currency units), not cents. Examples:

€500.00 is represented as 500.00
€1,250.50 is represented as 1250.50

Currency Codes

All currencies use ISO 4217 three-letter codes:

EUR - Euro
GBP - British Pound
USD - US Dollar

Dates and Timestamps

Dates: ISO 8601 date format (YYYY-MM-DD)
Timestamps: ISO 8601 datetime format (YYYY-MM-DDTHH:mm:ss.sssZ)

Status Values

Transaction Status

PendingTopUp - Waiting for top-up to settle
PendingReinvestment - Waiting for reinvestment
PendingDeposit - Waiting for deposit
Pending - Transaction pending
Cancelled - Transaction cancelled
Rejected - Transaction rejected
Settled - Transaction settled

Order Status

Pending - Order created but not matched
Matched - Order matched but not settled
Settled - Order fully settled
Rejected - Order rejected
Cancelled - Order cancelled

Bank Account Status

PendingVerification - Account pending verification
Active - Account active and verified
Disabled - Account disabled

Automation Status

Active - Automation is active
Inactive - Automation is inactive
Pending - Automation is pending activation

Example Export

View Complete Export Example

{
  "metadata": {
    "initiatedAt": "2025-01-16T01:00:00.000Z",
    "exportedAt": "2025-01-16T02:00:00.000Z",
    "schemaVersion": "1.1.1",
    "activityFrom": "2025-01-15T10:00:00.000Z",
    "activityTo": "2025-01-16T01:00:00.000Z"
  },
  "snapshots": [
    {
      "user": {
        "userId": "user_123",
        "email": "user@example.com"
      },
      "valuation": {
        "cash": {
          "value": 500.00,
          "currency": "EUR"
        },
        "savings": {
          "value": 1000.00,
          "currency": "EUR",
          "unrealisedMonthlyInterest": "12.50"
        },
        "holdings": {
          "value": 2500.00,
          "currency": "EUR",
          "upBy": "12.50"
        },
        "total": {
          "value": 4000.00,
          "currency": "EUR",
          "upBy": "15.00"
        }
      },
      "portfolio": [
        {
          "assetId": "equities_apple",
          "isin": "US0378331005",
          "quantity": 50,
          "latestPrice": {
            "amount": 175.50,
            "currency": "EUR"
          },
          "holdingWeightPercentage": 62.5,
          "dailyReturnPercentage": 0.5
        }
      ]
    }
  ],
  "activity": {
    "transactions": [
      {
        "owner": "user_123",
        "activityType": "Buy",
        "createdAt": "2025-01-15T10:30:00.000Z",
        "updatedAt": "2025-01-15T14:20:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 250.00,
        "details": {
          "orders": [
            {
              "isin": "IE00BK5BQT80",
              "side": "Buy",
              "quantity": 10,
              "consideration": {
                "amount": 250.00,
                "currency": "EUR"
              }
            }
          ]
        }
      },
      {
        "owner": "user_123",
        "activityType": "Sell",
        "createdAt": "2025-01-15T11:00:00.000Z",
        "updatedAt": "2025-01-15T13:00:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 150.00,
        "details": {
          "orders": [
            {
              "isin": "US0378331005",
              "side": "Sell",
              "quantity": 5,
              "consideration": {
                "amount": 150.00,
                "currency": "EUR"
              }
            }
          ]
        }
      },
      {
        "owner": "user_123",
        "activityType": "Rebalance",
        "createdAt": "2025-01-15T08:00:00.000Z",
        "updatedAt": "2025-01-15T16:00:00.000Z",
        "status": "Settled",
        "details": {
          "orders": [
            {
              "isin": "IE00BK5BQT80",
              "side": "Buy",
              "quantity": 15,
              "consideration": {
                "amount": 375.00,
                "currency": "EUR"
              }
            },
            {
              "isin": "US0378331005",
              "side": "Sell",
              "quantity": 8,
              "consideration": {
                "amount": 125.00,
                "currency": "EUR"
              }
            }
          ]
        }
      },
      {
        "owner": "user_123",
        "activityType": "Dividends",
        "createdAt": "2025-01-15T09:30:00.000Z",
        "updatedAt": "2025-01-15T09:30:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 25.50,
        "details": {
          "orders": [
            {
              "isin": "IE00BK5BQT80",
              "side": "Buy",
              "quantity": 0,
              "consideration": {
                "amount": 25.50,
                "currency": "EUR"
              }
            }
          ]
        }
      },
      {
        "owner": "user_123",
        "activityType": "Deposit",
        "createdAt": "2025-01-15T09:00:00.000Z",
        "updatedAt": "2025-01-15T12:00:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 1000.00,
        "bankAccount": "bank_account_505",
        "details": null
      },
      {
        "owner": "user_123",
        "activityType": "Withdraw",
        "createdAt": "2025-01-15T11:00:00.000Z",
        "updatedAt": "2025-01-15T13:00:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 500.00,
        "bankAccount": "bank_account_505",
        "details": null
      },
      {
        "owner": "user_123",
        "activityType": "CashToSavings",
        "createdAt": "2025-01-15T08:00:00.000Z",
        "updatedAt": "2025-01-15T10:00:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 100.50,
        "details": {
          "savingsProductId": "mmf_dist_eur"
        }
      },
      {
        "owner": "user_123",
        "activityType": "SavingsToCash",
        "createdAt": "2025-01-15T14:00:00.000Z",
        "updatedAt": "2025-01-15T15:00:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 50.00,
        "details": {
          "savingsProductId": "mmf_dist_eur"
        }
      },
      {
        "owner": "user_123",
        "activityType": "SavingsInterest",
        "createdAt": "2025-01-15T00:00:00.000Z",
        "updatedAt": "2025-01-15T00:00:00.000Z",
        "status": "Settled",
        "currency": "EUR",
        "amount": 0.42,
        "details": {
          "savingsProductId": "mmf_dist_eur"
        }
      }
    ],
    "investmentOrders": [
      {
        "id": "order_789",
        "owner": "user_123",
        "transactionId": "txn_456",
        "isin": "IE00BK5BQT80",
        "assetId": "equities_apple",
        "side": "Buy",
        "status": "Settled",
        "quantity": 10,
        "consideration": {
          "amount": 250.00,
          "currency": "EUR",
          "amountSubmitted": 250.00,
          "originalAmount": 248.00
        },
        "fees": {
          "fx": {
            "amount": 0.45,
            "currency": "EUR"
          },
          "commission": {
            "amount": 1.00,
            "currency": "EUR"
          }
        },
        "partnerFees": {
          "fx": {
            "amount": 0.05,
            "currency": "EUR"
          },
          "commission": {
            "amount": 1.50,
            "currency": "EUR"
          }
        },
        "unitPrice": {
          "amount": 25.00,
          "currency": "EUR"
        },
        "exchangeRate": null,
        "createdAt": "2025-01-15T10:30:00.000Z",
        "updatedAt": "2025-01-15T14:20:00.000Z",
        "filledAt": "2025-01-15T11:15:00.000Z",
        "marketSettledAt": "2025-01-15T14:20:00.000Z"
      }
    ],
    "savingsOrders": [
      {
        "id": "savings_order_202",
        "owner": "user_123",
        "side": "Buy",
        "status": "Settled",
        "currency": "EUR",
        "amount": 100.50,
        "savingsProductId": "mmf_dist_eur",
        "createdAt": "2025-01-15T08:00:00.000Z",
        "updatedAt": "2025-01-15T10:00:00.000Z",
        "settledAt": "2025-01-15"
      }
    ],
    "automations": [
      {
        "id": "automation_303",
        "owner": "user_123",
        "category": "TopUpAutomation",
        "status": "Active",
        "frequency": "monthly",
        "dayOfMonth": 15,
        "currency": "EUR",
        "amount": 500.00,
        "allocationMethod": "holdings",
        "mandate": {
          "id": "mandate_404",
          "status": "Active",
          "bankAccountId": "bank_account_505"
        },
        "createdAt": "2025-01-15T07:00:00.000Z",
        "updatedAt": "2025-01-15T07:00:00.000Z"
      },
      {
        "id": "automation_304",
        "owner": "user_123",
        "category": "RebalanceAutomation",
        "status": "Active",
        "frequency": "monthly",
        "createdAt": "2025-01-15T07:00:00.000Z",
        "updatedAt": "2025-01-15T07:00:00.000Z"
      }
    ],
    "bankAccounts": [
      {
        "id": "bank_account_505",
        "owner": "user_123",
        "accountName": "Main Account",
        "accountNumber": "GB82WEST12345698765432",
        "bankName": "Test Bank",
        "holderName": "John Doe",
        "status": "Active",
        "createdAt": "2025-01-15T06:00:00.000Z",
        "updatedAt": "2025-01-15T06:00:00.000Z"
      }
    ]
  }
}

JSON Schema

The complete JSON Schema definition is available for download and validation:

Download Schema

Download the complete JSON Schema file for data exports. Use this schema to validate exported data or integrate with your data platform tools.

Schema Versioning

Schema versions follow semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Breaking changes (structure changes, removed fields)
MINOR: New optional fields added
PATCH: Documentation updates, clarifications

The metadata.schemaVersion field indicates the schema version used for each export. Monitor this field to handle schema evolution in your data platform.

​Overview

​Export API

​Activity window options

​Export Structure

​Metadata

​Snapshots

​Activity

​Data Model

​Snapshot Structure

​Activity Structure

​Data Formats

​Amounts

​Currency Codes

​Dates and Timestamps

​Status Values

​Example Export

​JSON Schema

Download Schema

​Schema Versioning

Overview

Export API

Activity window options

Export Structure

Metadata

Snapshots

Activity

Data Model

Snapshot Structure

Activity Structure

Data Formats

Amounts

Currency Codes

Dates and Timestamps

Status Values

Example Export

JSON Schema

Schema Versioning