API documentation

Register

Create a new account. Returns a JWT token and client profile.

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "password": "securepassword"
}

Log in

Authenticate with email and password. Returns a JWT token.

{
  "email": "jane@example.com",
  "password": "securepassword"
}

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "client": {
      "id": "c_abc123",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "emailVerified": true,
      "persons": [],
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  }
}

Using the token

Include the token as a Bearer token in subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Refresh token

Exchange a valid token for a new one with the current subscription tier. Call this after subscription changes take effect.

Current client

Returns the authenticated client's profile, including linked persons.

Permanently delete the authenticated client and all associated data.

Password management

Change password for the authenticated client. Requires currentPassword and newPassword.

Send a password reset email. Requires email.

Reset password using a token from the reset email. Requires token and newPassword.

Email verification

Verify an email address using the token sent during registration.

Resend the verification email for the authenticated client.

Example: ISA investment

{
  "name": "Stocks and shares ISA",
  "type": "investment",
  "subType": "ISA",
  "personId": "p_abc123",
  "startingValue": "85000",
  "startMonth": 4,
  "startYear": 2026,
  "growthRate": {
    "mode": "percentage",
    "period": "annual",
    "value": "5.0"
  },
  "contribution": {
    "amount": "1000",
    "period": "monthly"
  },
  "drawdownOrder": 2
}

Example: PCLS drawdown pension

{
  "name": "Workplace pension",
  "type": "pension",
  "subType": "PCLS_DRAWDOWN",
  "personId": "p_abc123",
  "startingValue": "320000",
  "startMonth": 4,
  "startYear": 2026,
  "growthRate": {
    "mode": "percentage",
    "period": "annual",
    "value": "4.5"
  },
  "contribution": {
    "amount": "500",
    "period": "monthly",
    "endMonth": 3,
    "endYear": 2045
  },
  "pclsPercentage": "25",
  "pclsTargetId": "elem_isa_123",
  "drawdownOrder": 3,
  "drawdownStartMonth": 4,
  "drawdownStartYear": 2045
}

The pclsPercentage sets the tax-free lump sum as a percentage of the fund at crystallisation. pclsTargetId is the element that receives the lump sum (for example, an ISA or savings account). Alternatively, use pclsAmount for a fixed amount.

Example: employment income

{
  "name": "Salary",
  "type": "income",
  "personId": "p_abc123",
  "startingValue": "65000",
  "startMonth": 4,
  "startYear": 2026,
  "endMonth": 3,
  "endYear": 2045,
  "growthRate": {
    "mode": "percentage",
    "period": "annual",
    "value": "2.5"
  }
}

Common fields

Growth rate

Every element requires a growth rate. All three fields are required.

Contribution

Stage-linked dates

Instead of fixed dates, element start, end, contribution end, drawdown start, and liquidation dates can be linked to a stage boundary. Use the *StageId and *StageEdge fields:

{
  "startDateStageId": 2,
  "startDateStageEdge": "start",
  "endDateStageId": 3,
  "endDateStageEdge": "end"
}

When a stage's dates change, all elements linked to it shift automatically.

Liquidation

Elements can have a one-off liquidation event - for example, selling a property or crystallising a pension.

Pension-specific fields

Response

The response contains a summary, an array of monthlySnapshots, and effectiveDates for each element.

{
  "data": {
    "summary": {
      "totalMonths": 528,
      "finalNetWorth": "1245000.00",
      "finalInflationAdjustedNetWorth": "780000.00",
      "totalIncomeGenerated": "2850000.00",
      "totalExpensesIncurred": "1920000.00",
      "totalTaxPaid": "485000.00",
      "totalTaxFreeIncome": "120000.00",
      "totalDrawdown": "340000.00"
    },
    "monthlySnapshots": [
      {
        "date": "2026-04",
        "totalNetWorth": "405000.00",
        "inflationAdjustedNetWorth": "405000.00",
        "totalIncome": "5416.67",
        "totalExpenses": "3200.00",
        "totalTax": "890.00",
        "totalTaxFreeIncome": "0",
        "netIncomeAfterTax": "1326.67",
        "netCashFlow": "1326.67",
        "totalDrawdown": "0",
        "remainingLSA": "1073100.00",
        "elements": [
          {
            "elementId": "elem_123",
            "name": "Stocks and shares ISA",
            "type": "investment",
            "value": "86000.00"
          }
        ],
        "personTaxDetails": [
          {
            "personId": "p_abc123",
            "personName": "Jane Smith",
            "taxableIncome": "5416.67",
            "taxFreeIncome": "0",
            "netIncome": "4526.67",
            "taxDue": "890.00",
            "bands": [
              {
                "bandName": "Basic rate",
                "rate": "0.20",
                "income": "4370.83",
                "tax": "874.17"
              }
            ]
          }
        ]
      }
    ],
    "effectiveDates": [
      {
        "elementId": "elem_123",
        "name": "Stocks and shares ISA",
        "type": "investment",
        "startDate": "2026-04",
        "endDate": "2070-03",
        "contributionEndDate": "2070-03",
        "drawdownStartDate": "2045-04"
      }
    ]
  }
}

Each monthly snapshot includes per-element values, per-person tax breakdowns with band detail, and aggregate totals. The inflationAdjustedNetWorth reports net worth in today's purchasing power.

Submit a simulation

Returns 202 Accepted with a job ID.

{
  "startMonth": 4,
  "startYear": 2026,
  "endMonth": 3,
  "endYear": 2070,
  "simulations": 1000,
  "annualVolatility": 15.0,
  "targetMonth": 3,
  "targetYear": 2060
}

Response:

{
  "data": {
    "jobId": "job_xyz789",
    "type": "simulation",
    "status": "pending"
  }
}

Poll for results

Use the jobs endpoint to check status and retrieve results once complete. The result contains P10/P25/P50/P75/P90 percentile bands for net worth at each month, plus a success rate if a target date was provided.

Element overrides

Override any element field for the duration of the run. Only elementId is required; include only the fields you want to change. Use remove* flags (e.g. removeContribution: true) to clear optional fields.

Stage overrides

Shift stage boundaries. Requires stageId; include startMonth, startYear, endMonth, endYear as needed.

Person overrides

Adjust a person's lsaUsed or otherAnnualIncome for the run.