# Loanie — Full Documentation

> Home loans made simple. A New Zealand mortgage and loan platform with local advisors available 24/7.

Loanie (https://loanie.co.nz) helps New Zealanders find and apply for home loans, compare mortgage rates from 30+ banks, search property values, calculate repayments, and connect with expert mortgage advisors.

---

## Agent Discovery

Use these machine-readable entry points first:

- **MCP manifest**: `https://loanie.co.nz/.well-known/mcp.json`
- **Skills guide**: `https://loanie.co.nz/skills.md`
- **OpenAI function calling**: `https://loanie.co.nz/.well-known/openai-function-calling.json`
- **Short overview**: `https://loanie.co.nz/llms.txt`
- **AI-ready page**: `https://loanie.co.nz/en/ai-ready`

---

## MCP Server

Loanie exposes a Model Context Protocol (MCP) server that AI assistants can connect to for real-time NZ mortgage data and loan operations.

- **Endpoint**: `https://loanie.co.nz/api/mcp`
- **Transport**: Streamable HTTP (JSON responses enabled)
- **Discovery file**: `https://loanie.co.nz/.well-known/mcp.json`
- **Protocol**: MCP v1.0.0
- **Server name**: `loanie`

### Connection

Connect using any MCP-compatible client:

```json
{
  "mcpServers": {
    "loanie": {
      "url": "https://loanie.co.nz/api/mcp",
      "transport": "streamable-http"
    }
  }
}
```

---

## OpenAI Function Calling

Loanie also publishes OpenAI-compatible function definitions for the Responses API.

- **Definitions file**: `https://loanie.co.nz/.well-known/openai-function-calling.json`
- **Guide basis**: `https://developers.openai.com/api/docs/guides/function-calling`
- **Schema mode**: strict (`strict: true`)
- **Recommendation**: set `parallel_tool_calls` to `false` and confirm intent before calling `submit_loan_application`

### Minimal usage

```ts
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const { tools } = await fetch(
  "https://loanie.co.nz/.well-known/openai-function-calling.json",
).then((res) => res.json());

const response = await openai.responses.create({
  model: "gpt-5.4",
  input: "Compare current 1-year special mortgage rates from ANZ, ASB, BNZ, Westpac, and Kiwibank.",
  tools,
  tool_choice: "auto",
  parallel_tool_calls: false,
});
```

Notes:

- Optional inputs are represented as nullable required fields so the published schemas stay strict-mode compatible.
- For side-effecting actions, require an explicit user confirmation step before the tool call.
- The MCP endpoint remains the better choice when the client already supports remote MCP servers.

---

## MCP Tools Reference

### get_mortgage_rates

Get current mortgage interest rates from major New Zealand banks (ANZ, ASB, BNZ, Westpac, Kiwibank, SBS, and 30+ more). Data sourced from ratesapi.nz, cached hourly.

**Parameters**: None

**Returns**: Object with `lastUpdated` timestamp, `fromCache` boolean, and `rates` grouped by institution. Each rate entry has `product`, `term`, and `rate` fields.

**Example response**:
```json
{
  "lastUpdated": "2025-01-15T03:00:00Z",
  "fromCache": true,
  "rates": {
    "ANZ": [
      { "product": "Standard", "term": "1 year", "rate": 5.99 },
      { "product": "Standard", "term": "2 years", "rate": 5.79 }
    ]
  }
}
```

---

### search_addresses

Search for New Zealand property addresses by free-text query. Returns up to 10 matching addresses with coordinates, suburb, city, and property IDs.

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | Yes | Address search query, e.g. "123 Queen Street Auckland" |

**Returns**: Array of address results with `address`, `suburb`, `city`, `lat`, `long`, `streetNumber`, `street`, `propertyId`.

Use the returned `propertyId` with `get_property_details` for full property information.

---

### get_property_details

Get detailed information about a New Zealand property: estimated value, bedrooms, bathrooms, floor/land area, images.

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| propertyId | string | No | Property ID from search_addresses results |
| address | string | No | Full address to auto-resolve if propertyId unavailable |

At least one of `propertyId` or `address` must be provided.

**Returns**: Object with `propertyId`, `estimatedValue`, `estimatedRange` (low/high), `displayValue`, `capitalValue`, `bedrooms`, `bathrooms`, `carSpaces`, `floorArea`, `landArea`, `landUse`, `suburb`, `city`, `images`.

---

### submit_loan_application

Submit a mortgage or loan application to Loanie. No account required — an expert advisor will review and follow up via email/phone.

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| loanType | enum | Yes | One of: HOME_PURCHASE, REFINANCE, INVESTMENT, BUILD_DEVELOPMENT, AUTO_LOAN, HOME_EQUITY, PERSONAL_LOAN, BUSINESS_LOAN |
| fullName | string | Yes | Applicant's full name |
| email | string | Yes | Applicant's email address |
| phone | string | No | Phone number (NZ format preferred) |
| propertyAddress | string | No | Property address (for purchase/refinance) |
| propertyValue | number | No | Estimated property value in NZD |
| downPayment | number | No | Down payment / deposit amount in NZD |
| referralCode | string | No | Referral/invitation code if referred |

**Returns**: Object with `success`, `caseNumber`, `message`, and `nextSteps` array.

**Important**: This tool creates a real loan application. An expert advisor will contact the applicant. Only call when the user explicitly wants to submit an application.

---

### estimate_break_fee

Calculate the estimated break fee for exiting a fixed-rate NZ mortgage early.

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| bank | enum | Yes | One of: ANZ, ASB, BNZ, Kiwibank, TSB, Westpac, Co-operative Bank, SBS, HSBC |
| loanAmount | number | Yes | Outstanding loan balance in NZD |
| fixedRate | number | Yes | Current fixed interest rate (e.g. 5.99) |
| originalTermMonths | number | Yes | Original fixed term in months (e.g. 12) |
| fixedInstallment | number | Yes | Monthly payment amount in NZD |
| dateFixedTermBegan | string | Yes | Date fixed term began (YYYY-MM-DD) |

**Returns**: Object with `breakFee`, `prepaymentAmount`, `totalPayment`, `calculationMethod`, and `note`.

---

### get_invitation_info

Look up a Loanie referral/invitation code to see who sent it, the invitation type, attached property info, and assigned expert advisor.

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| code | string | Yes | The invitation/referral code |

**Returns**: Object with `code`, `type`, `status`, `inviterName`, `usedCount`, `property` (address, value, bedrooms, bathrooms, suburb, city), `expert` (name, title), and `applyUrl`.

---

### calculate_repayment

Calculate mortgage repayment amounts for a given loan.

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| principal | number | Yes | Loan amount in NZD (e.g. 600000) |
| annualRate | number | Yes | Annual interest rate as percentage (e.g. 5.99) |
| termYears | number | Yes | Loan term in years (e.g. 30) |

**Returns**: Object with `monthlyPayment`, `fortnightlyPayment`, `weeklyPayment`, `totalInterest`, `totalCost`, `principal`, `annualRate`, `termYears`.

**Example**:
```json
{
  "monthlyPayment": 3593.26,
  "fortnightlyPayment": 1796.63,
  "weeklyPayment": 829.21,
  "totalInterest": 693573,
  "totalCost": 1293573,
  "principal": 600000,
  "annualRate": 5.99,
  "termYears": 30
}
```

---

### calculate_borrowing_capacity

Estimate how much a borrower may be able to borrow for a New Zealand home loan based on income, expenses, dependants, and deposit. Uses a stress-test rate of current best major-bank pricing plus 2.5%.

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| annualIncome | number | Yes | Total annual income before tax in NZD |
| otherAnnualIncome | number | No | Other annual income such as rent or investments; defaults to 0 |
| dependants | integer | No | Number of dependant children under 18; defaults to 0 |
| monthlyExpenses | number | Yes | Total monthly living expenses in NZD |
| monthlyExistingLoans | number | No | Monthly existing loan repayments in NZD; defaults to 0 |
| deposit | number | Yes | Total deposit or savings available in NZD |
| termYears | integer | No | Loan term in years; defaults to 30 |
| referralCode | string | No | Referral or invitation code if referred |

**Returns**: Object with `maxBorrowing`, `estimatedMonthlyRepayment`, `maxPropertyValue`, `lvrPercent`, `deposit`, `currentBestRate`, `stressTestRate`, `termYears`, and `calculatorUrl`.

---

## Public Pages

| Page | URL | Description |
|------|-----|-------------|
| Home | https://loanie.co.nz | Landing page with live mortgage rates and loan application CTA |
| Apply | https://loanie.co.nz/onboarding | Guided multi-step loan application flow |
| Rates | https://loanie.co.nz/rates | Compare mortgage rates across 30+ NZ banks |
| Refinance Calculator | https://loanie.co.nz/refinance-calculator | Refinancing repayment calculator |
| Chat | https://loanie.co.nz/chat | Live chat with expert mortgage advisors |
| For Agents | https://loanie.co.nz/why-agent | Real estate agent partnership program |
| For Lawyers | https://loanie.co.nz/why-lawyer | Lawyer partnership program |
| Refer a Friend | https://loanie.co.nz/why-frens | Referral rewards program |
| AI Ready | https://loanie.co.nz/en/ai-ready | MCP, skills.md, and OpenAI function-calling guide |
| Invitation | https://loanie.co.nz/invite/{code} | Referral invitation landing page |
| About | https://loanie.co.nz/resources/about | About Loanie |
| FAQ | https://loanie.co.nz/resources/faq | Frequently asked questions |
| Guides | https://loanie.co.nz/resources/guides | Home loan guides and resources |
| Docs | https://loanie.co.nz/resources/docs | Documentation and support |
| Privacy | https://loanie.co.nz/resources/privacy | Privacy policy |
| Terms | https://loanie.co.nz/resources/tos | Terms of service |
| Cookies | https://loanie.co.nz/resources/cookies | Cookie policy |
| Licenses | https://loanie.co.nz/resources/licenses | Licenses and regulatory info |
| Disclosure | https://loanie.co.nz/resources/disclosure | Financial disclosure statements |
| Feedback | https://loanie.co.nz/resources/feedback-and-complaints | Feedback and complaints |
| Careers | https://loanie.co.nz/resources/careers | Career opportunities |
| Skills Guide | https://loanie.co.nz/skills.md | Agent-readable workflow guide |
| OpenAI Function Calling | https://loanie.co.nz/.well-known/openai-function-calling.json | Strict-mode function definitions for Responses API |

---

## Supported Loan Types

| Type | Enum Value | Description |
|------|-----------|-------------|
| Home Purchase | HOME_PURCHASE | Buying a new home |
| Refinance | REFINANCE | Switching from an existing mortgage |
| Investment | INVESTMENT | Investment property financing |
| Build / Development | BUILD_DEVELOPMENT | Construction or development lending |
| Auto Loan | AUTO_LOAN | Vehicle financing |
| Home Equity | HOME_EQUITY | Borrowing against home equity |
| Personal Loan | PERSONAL_LOAN | Unsecured personal loans |
| Business Loan | BUSINESS_LOAN | Business financing |

---

## Supported Banks (for rate comparison)

ANZ, ASB, BNZ, Westpac, Kiwibank, SBS Bank, TSB, Co-operative Bank, HSBC, and 20+ additional NZ lenders.

---

## Internationalization

Loanie supports 9 languages:

| Language | Locale Code |
|----------|-------------|
| English | en |
| Te Reo Māori | mi |
| Simplified Chinese | zh-CN |
| Traditional Chinese | zh-TW |
| Korean | ko |
| Japanese | ja |
| Vietnamese | vi |
| Hindi | hi |
| Punjabi | pa |

All public pages are available in each language at `https://loanie.co.nz/{locale}/...`

---

## Contact

| Purpose | Email |
|---------|-------|
| General inquiries | hello@loanie.co.nz |
| Support | support@loanie.co.nz |
| Privacy | privacy@loanie.co.nz |
| Legal | legal@loanie.co.nz |
| Feedback | feedback@loanie.co.nz |
| Careers | careers@loanie.co.nz |