Schema Overview

Data Schemas

The Quickli Public API uses comprehensive, validated schemas for all requests and responses. All schemas are defined using Zod and automatically generate TypeScript types and OpenAPI documentation.

Available Schemas

Core Schemas

• Scenario Schema - Complete mortgage scenario structure including households, income, securities, loans, liabilities, and expenses
• Servicing Result Schema - Detailed servicing calculation results including borrowing capacity, validations, and rate breakdowns
• Product Schema - Lender product information with rate tables and product features
• Policy Schema - Lending policy documents with triggers and content

Schema Validation

All API requests are validated against Zod schemas before processing. If validation fails, you’ll receive a 422 Validation Error with detailed information about what went wrong.

Example Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "issues": [
        {
          "path": ["scenario", "households", 0, "postcode"],
          "message": "Expected number, received string"
        }
      ]
    },
    "timestamp": "2025-11-03T10:30:00.000Z"
  }
}

Field Conventions

Required vs Optional

• Required fields: Must be provided in every request
• Optional fields: Can be omitted; sensible defaults will be applied

Fields marked as optional in the schema will have TypeScript type T | undefined.

Data Types

Type	Description	Example
string	Text value	"hello"
number	Numeric value (integer or float)	123, 45.67
boolean	True or false	true, false
array	List of values	[1, 2, 3]
object	Nested structure	{ "key": "value" }
enum	One of a fixed set of values	"owner_occupied", "investment"
union	One of multiple types	string | number

ObjectIds

MongoDB ObjectIds are represented as 24-character hexadecimal strings:

"507f1f77bcf86cd799439011"

Valid format: Exactly 24 characters, hexadecimal (0-9, a-f)

Dates and Timestamps

All dates and timestamps use ISO 8601 format:

"2025-11-03T10:30:00.000Z"

Using Schemas in Your Code

TypeScript

The API provides TypeScript types that match the Zod schemas:

import type {
  SaveableScenario,
  ServicingResult,
  LenderProduct,
  Policy
} from '@quickli/validation';

// Type-safe scenario creation
const scenario: SaveableScenario = {
  households: [{
    id: 'household-1',
    status: 'single',
    num_adults: 1,
    num_dependants: 0,
    postcode: 2000,
    shared_with_households: []
  }],
  income: [],
  securities: [],
  home_loans: [],
  liabilities: [],
  living_expenses: [],
  // ... other fields
};

JavaScript

For plain JavaScript, follow the schema structure:

const scenario = {
  households: [{
    id: 'household-1',
    status: 'single',
    num_adults: 1,
    num_dependants: 0,
    postcode: 2000,
    shared_with_households: []
  }],
  income: [],
  securities: [],
  // ... other fields
};

Python

from typing import TypedDict, List, Optional

class Household(TypedDict):
    id: str
    status: str  # 'single' | 'couple' | ...
    num_adults: int
    num_dependants: int
    postcode: int
    shared_with_households: List[str]

class Scenario(TypedDict):
    households: List[Household]
    income: List[dict]
    securities: List[dict]
    # ... other fields

Schema Defaults

Many fields have sensible defaults that are applied when not provided:

Scenario Defaults

• Empty arrays for all list fields (households, income, securities, etc.)
• Default configuration objects for additional_info
• Standard calculation settings

Example: Minimal Scenario

This minimal scenario will have defaults applied:

{
  "scenario": {}
}

Becomes:

{
  "scenario": {
    "households": [],
    "income": [],
    "securities": [],
    "home_loans": [],
    "liabilities": [],
    "living_expenses": [],
    "rental_income": [],
    "self_employed_income": [],
    "home_loan_security_links": [],
    "additional_info": {
      "useDependantAges": false
      // ... other defaults
    }
  }
}

Enum Values

Many fields use enums to restrict values to a specific set. Here are the most common:

Household Status

'single' | 'couple' | 'de_facto' | 'divorced' | 'separated' | 'widowed'

Property Transaction Type

'purchasing' | 'refinancing' | 'owned'

Property Type

'house' | 'unit' | 'townhouse' | 'apartment' | 'land' | 'rural' | 'commercial' | 'industrial'

Property Purpose

'owner_occupied' | 'investment'

Loan Type

'owner_occupied' | 'investment'

Product Type

'variable_package' | 'variable_basic' | 'fixed' | 'line_of_credit' | 'construction'

Existing or Proposed

'existing' | 'proposed'

Liability Type

'credit_card' | 'personal_loan' | 'car_loan' | 'student_loan' | 'other_liability'

Validation Rules

Common Validations

• Positive numbers: Values like loan amounts must be > 0
• Percentages: Values like LVR must be 0-100
• Postal codes: Australian postal codes (1000-9999)
• Email format: Must be valid email address
• ObjectId format: Must be 24-character hex string
• Array minimums: Some arrays require at least 1 item

Example: Scenario Validation

{
  households: z.array(HouseholdSchema).min(0),  // 0 or more households
  income: z.array(IncomeSchema).min(0),         // 0 or more income sources
  securities: z.array(SecuritySchema).min(0),   // 0 or more properties
  // ... more fields
}

OpenAPI Schema

The complete OpenAPI 3.0 schema is available at:

https://api.quickli.com/api/v1/openapi.json

You can use this to:

• Generate client libraries in any language
• Validate requests/responses in your tests
• Import into API development tools (Postman, Insomnia, etc.)

Next Steps

• Browse scenario schema - Learn about the mortgage scenario structure
• Review servicing results - Understand calculation outputs
• Explore endpoints - See how schemas are used in API calls

---

Last updated: 2025-11-03