GET /scenarios/[id]

GET /api/v1/scenarios/[id]

Get a scenario by ID.

Overview

Retrieves a complete scenario including all applicant details, properties, loans, income, and expenses.

Authentication

Required: RSA signature-based authentication

X-Auth-Client-ID: {clientId}
X-Auth-Access-Token: {accessToken}
X-Auth-Timestamp: {timestamp}
X-Auth-Nonce: {nonce}
X-Auth-Signature: {signature}

Request

Method: GET

URL: https://api.quickli.com/api/v1/scenarios/id

Path Parameters:

id (required) - Scenario ObjectId (24-character hex string)

Headers:

X-Auth-Client-ID: {clientId}
X-Auth-Access-Token: {accessToken}
X-Auth-Timestamp: {timestamp}
X-Auth-Nonce: {nonce}
X-Auth-Signature: {signature}
Content-Type: application/json

Body: None

Response

Success Response (200 OK)

{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "teamId": "507f191e810c19729de860ea",
    "description": "First home buyer scenario",
    "createdBy": "broker@example.com",
    "dateCreated": "2025-11-03T10:30:00.000Z",
    "lastEditedBy": "broker@example.com",
    "lastEditedOn": "2025-11-03T10:30:00.000Z",
    "scenario": {
      "households": [
        /* ... */
      ],
      "income": [
        /* ... */
      ],
      "securities": [
        /* ... */
      ],
      "home_loans": [
        /* ... */
      ],
      "liabilities": [
        /* ... */
      ],
      "living_expenses": [
        /* ... */
      ],
      "rental_income": [
        /* ... */
      ],
      "self_employed_income": [
        /* ... */
      ],
      "home_loan_security_links": [
        /* ... */
      ],
      "additional_info": {
        /* ... */
      }
    }
  },
  "meta": {
    "timestamp": "2025-11-03T10:30:00.000Z",
    "version": "1.0.0"
  }
}

Error Responses

401 Unauthorized

Invalid credentials.

403 Forbidden

Scenario belongs to a team you don’t have access to.

404 Not Found

Scenario doesn’t exist or you don’t have permission to view it.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Scenario not found: 507f1f77bcf86cd799439011",
    "timestamp": "2025-11-03T10:30:00.000Z"
  }
}

Note: For security reasons, we return 404 (not 403) when you don’t have access to an existing scenario.

Code Examples

curl -X GET https://api.quickli.com/api/v1/scenarios/507f1f77bcf86cd799439011 \
-H "X-Auth-Client-ID: {clientId}" \
-H "X-Auth-Access-Token: {accessToken}" \
-H "X-Auth-Timestamp: {timestamp}" \
-H "X-Auth-Nonce: {nonce}" \
-H "X-Auth-Signature: {signature}" \
-H "Content-Type: application/json"

// See Authentication Guide for generateAuthHeaders implementation
async function getScenario(scenarioId: string) {
  const path = `/api/v1/scenarios/${scenarioId}`;
  const headers = generateAuthHeaders('GET', path, {});

  const response = await fetch(
    `https://api.quickli.com${path}`,
    {
      method: 'GET',
      headers
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const result = await response.json();
  return result.data;
}

// Usage
const scenario = await getScenario('507f1f77bcf86cd799439011');
console.log('Scenario:', scenario.description);
console.log('Households:', scenario.scenario.households.length);
console.log('Income sources:', scenario.scenario.income.length);

# See Authentication Guide for generate_auth_headers implementation
def get_scenario(scenario_id):
    path = f'/api/v1/scenarios/{scenario_id}'
    headers = generate_auth_headers('GET', path, None)

    response = requests.get(
        f'https://api.quickli.com{path}',
        headers=headers
    )

    response.raise_for_status()
    return response.json()['data']

# Usage
scenario = get_scenario('507f1f77bcf86cd799439011')
print(f"Scenario: {scenario['description']}")
print(f"Households: {len(scenario['scenario']['households'])}")

Use Cases

1. Retrieve for Editing

Get scenario before making changes:

const scenario = await getScenario(scenarioId);

// Modify scenario
scenario.scenario.income.push({
  id: 'new-income',
  which_household: 0,
  name: 'Additional Income',
  payg: 20000,
  // ... other fields
});

// Update scenario
await updateScenario(scenarioId, {
  scenario: scenario.scenario
});

2. Display to User

Show scenario details in UI:

const scenario = await getScenario(scenarioId);

console.log(`Description: ${scenario.description}`);
console.log(`Created: ${new Date(scenario.dateCreated).toLocaleDateString()}`);
console.log(`By: ${scenario.createdBy}`);
console.log(`\nDetails:`);
console.log(`- ${scenario.scenario.households.length} household(s)`);
console.log(`- ${scenario.scenario.income.length} income source(s)`);
console.log(`- ${scenario.scenario.securities.length} property/ies`);
console.log(`- ${scenario.scenario.home_loans.length} loan(s)`);

3. Verify Scenario Exists

Check if scenario is accessible before performing operations:

async function ensureScenarioExists(scenarioId: string): Promise<boolean> {
  try {
    await getScenario(scenarioId);
    return true;
  } catch (error) {
    if (error.message.includes('not found')) {
      return false;
    }
    throw error;
  }
}

// Before computing servicing
if (!await ensureScenarioExists(scenarioId)) {
  console.error('Scenario not found');
  return;
}

await computeServicing(scenarioId, {lenderName: 'cba'});

Authorization

The scenario must belong to a team in your access grant. Authorization checks:

User authentication: Valid RSA signature
Team access: Scenario’s teamId must be in your accessible teams
Scenario ownership: Scenario must exist and belong to accessible team

If any check fails, you’ll receive a 401, 403, or 404 error.

Response Structure

The response includes both metadata and the scenario itself:

Metadata:

id - Scenario ObjectId
teamId - Team this scenario belongs to
description - Scenario title/description
createdBy - Email of creator
dateCreated - Creation timestamp
lastEditedBy - Email of last editor
lastEditedOn - Last edit timestamp

Scenario Data:

Complete scenario structure (see scenario schema)