PATCH /scenarios/[id]

PATCH /api/v1/scenarios/[id]

Partially update an existing scenario.

Overview

Updates specific fields in a scenario without affecting other fields. This endpoint uses PATCH semantics - you only need to include the fields you want to update. All other fields will remain unchanged.

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: PATCH

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

Path Parameters:

id (required) - Scenario ObjectId

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 (at least one field required):

{
  "households": [...],
  "income": [...],
  "rental_income": [...],
  "securities": [...],
  "self_employed_income": [...],
  "home_loans": [...],
  "liabilities": [...],
  "living_expenses": [...],
  "additional_info": {...}
}

Only include the fields you want to update. Omitted fields will not be modified.

For example, to update only households:

{
  "households": [...]
}

This will update households while preserving all other fields like income, liabilities, etc.

Response

Success Response (200 OK)

Returns the complete updated scenario (same format as GET).

{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "teamId": "507f191e810c19729de860ea",
    "description": "Family home purchase",
    "createdBy": "broker@example.com",
    "dateCreated": "2025-11-03T10:30:00.000Z",
    "lastEditedBy": "broker@example.com",
    "lastEditedOn": "2025-11-03T11:00:00.000Z",
    "scenario": { /* Complete updated scenario */ }
  },
  "meta": {
    "timestamp": "2025-11-03T11:00:00.000Z",
    "version": "v1"
  }
}

Error Responses

400 Bad Request

No fields provided for update.

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.

422 Validation Error

Invalid scenario data.

Code Examples

# Update only households
curl -X PATCH 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" \
  -d '{
    "households": [{
      "id": "household-1",
      "status": "single",
      "num_adults": 1,
      "num_dependants": 2,
      "postcode": 3000,
      "shared_with_households": []
    }]
  }'

# Update only income
curl -X PATCH 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" \
  -d '{
    "income": [{
      "id": "income-1",
      "which_household": 0,
      "payg": 120000
    }]
  }'

# Update multiple fields
curl -X PATCH https://api.quickli.com/api/v1/scenarios/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer ${CLIENT_SECRET}:${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "households": [...],
    "income": [...]
  }'

// See Authentication Guide for generateAuthHeaders implementation
async function updateScenario(
  scenarioId: string,
  updates: Partial<{
    households: Household[];
    income: Income[];
    rental_income: RentalIncome[];
    securities: Security[];
    self_employed_income: SelfEmployedIncome[];
    home_loans: HomeLoan[];
    liabilities: Liability[];
    living_expenses: LivingExpense[];
    additional_info: AdditionalInfo;
  }>
) {
  const path = `/api/v1/scenarios/${scenarioId}`;
  const headers = generateAuthHeaders('PUT', path, updates);

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

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

  return (await response.json()).data;
}

// Update only households
await updateScenario(scenarioId, {
  households: [{
    id: 'household-1',
    status: 'single',
    num_adults: 1,
    num_dependants: 2,
    postcode: 3000,
    shared_with_households: []
  }]
});

// Update only income
await updateScenario(scenarioId, {
  income: [{
    id: 'income-1',
    which_household: 0,
    payg: 120000
  }]
});

// Update multiple fields
await updateScenario(scenarioId, {
  households: [...],
  income: [...]
});

# See Authentication Guide for generate_auth_headers implementation
def update_scenario(scenario_id, **updates):
    """
    Update specific scenario fields.
        Only provided fields will be updated.
    """

    path = f'/api/v1/scenarios/{scenario_id}'
    headers = generate_auth_headers('PUT', path, payload)

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

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

# Update only households
update_scenario(
    scenario_id,
    households=[{
        'id': 'household-1',
        'status': 'single',
        'num_adults': 1,
        'num_dependants': 2,
        'postcode': 3000,
        'shared_with_households': []
    }]
)

# Update only income
update_scenario(
    scenario_id,
    income=[{
        'id': 'income-1',
        'which_household': 0,
        'payg': 120000
    }]
)

Use Cases

1. Update Household Details

Change postcode or number of dependants without affecting income or loans:

await updateScenario(scenarioId, {
  households: [{
    id: 'household-1',
    status: 'single',
    num_adults: 1,
    num_dependants: 3, // Changed from 2 to 3
    postcode: 2000,
    shared_with_households: []
  }]
});
// Income, home_loans, and all other fields remain unchanged

2. Add Income Source

Add a new income source without re-sending the entire scenario:

// Fetch current income
const scenario = await getScenario(scenarioId);

// Add new income
await updateScenario(scenarioId, {
  income: [
    ...scenario.scenario.income,
    {
      id: 'income-2',
      which_household: 0,
      payg: 25000
    }
  ]
});
// Households, liabilities, and all other fields remain unchanged

3. Modify Loan Amount

Update loan details without affecting applicant information:

const scenario = await getScenario(scenarioId);

scenario.scenario.home_loans[0].loan_amount = 700000;

await updateScenario(scenarioId, {
  home_loans: scenario.scenario.home_loans
});
// Income, households, and all other fields remain unchanged

4. Update Multiple Fields

Update households and income together while preserving other fields:

await updateScenario(scenarioId, {
  households: [...], // Updated households
  income: [...]      // Updated income
});
// liabilities, living_expenses, and all other fields remain unchanged

Comparison: PATCH vs Full Replacement

✅ PATCH (Current)

// Only send what you want to change
await updateScenario(scenarioId, {
  households: [...]
});
// Efficient - single DB operation
// Safe - other fields preserved

❌ Full Replacement (Old Approach)

// Had to fetch, modify, and send everything back
const scenario = await getScenario(scenarioId);
scenario.scenario.households = [...];
await updateScenario(scenarioId, {
  scenario: scenario.scenario // All fields required
});
// Less efficient - fetch + update
// Risk of race conditions

Notes

Partial updates: Only provided fields are modified - omitted fields remain unchanged
Efficient: Single database operation, no fetch required
Safe: No risk of overwriting fields you didn’t intend to change
Cannot change teamId: Team ownership is immutable after creation
lastEditedBy and lastEditedOn are automatically updated
At least one scenario field must be provided