# Plans and comparisons

A broker advises a client with a few tools in BrokerPlus: the mortgage plan builder, the offers on a
deal and their side-by-side comparison, deal scenarios, and strategy analyses. This page shows how
to read and build each one through the API. BrokerPlus sends nothing to the client from these
endpoints, so a key with the `no_sending` limit can use all of them.

This API is in beta. Any endpoint can change in a breaking way without notice, so watch the
[changelog](/changelog).

Every rate on this page is a percent: `4.79` means 4.79%. See [Units](/units).

## Who can see a plan

A key reaches the same plans, offers, and analyses its broker reaches in BrokerPlus. A plan on a
deal that belongs to another team is `404 NOT_FOUND`, the same as the deal itself. A key with the
`leads_only` limit reaches none of them. See [Authentication](/authentication).

## Mortgage plans

A mortgage plan shows a client up to 3 options side by side. Each option has its rate, term, and
amortization, the monthly housing costs, and the figures for a purchase, a sale, or a refinance.
The broker opens a plan you save in the plan builder, on the deal or the contact you attach it to.

`POST /v1/mortgage-plans` saves a plan. Attach it to a deal with `deal_id`, to a person with
`contact_id`, or to both when they are on the same team.

```bash
curl -X POST https://api.mos.getbrokerplus.ca/v1/mortgage-plans \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Jordan Lee purchase",
    "deal_id": "cm9d1a2b3000",
    "plan_type": "purchase_conventional",
    "province": "ON",
    "dwelling": "condo",
    "columns": [
      {"id": "a", "label": "5-year fixed", "rate": 4.79, "rate_type": "fixed", "term_months": 60,
       "amortization_years": 25, "purchase_price": 650000, "down_payment": 130000,
       "budget": {"condo_fees": 420}}
    ]
  }'
```

```json
{
  "success": true,
  "data": {
    "object": "mortgage_plan",
    "id": "cm9p7q8r9000",
    "title": "Jordan Lee purchase",
    "client_name": null,
    "deal_id": "cm9d1a2b3000",
    "contact_id": null,
    "plan_type": "purchase_conventional",
    "province": "ON",
    "dwelling": "condo",
    "first_time_buyer": false,
    "municipality": null,
    "notes": null,
    "columns": [
      {
        "id": "a",
        "label": "5-year fixed",
        "rate": 4.79,
        "rate_type": "fixed",
        "term_months": 60,
        "amortization_years": 25,
        "budget": { "condo_fees": 420 },
        "purchase_price": 650000,
        "down_payment": 130000
      }
    ],
    "refinance": null,
    "user_id": "cm8u1v2w3000",
    "created_at": "2026-10-09T14:02:11.000Z",
    "updated_at": "2026-10-09T14:02:11.000Z"
  }
}
```

`PATCH /v1/mortgage-plans/{id}` changes the fields you send. `columns` replaces every option, so
send each option you want to keep. `GET /v1/mortgage-plans` lists plans, and takes `deal_id`,
`contact_id`, and `updated_since`. See [Sync](/sync).

## Offers and the comparison

The offers tab on a deal holds the lender offers the broker is weighing, each with its fees. The
broker sees an offer you add on the deal straight away.

`POST /v1/deals/{id}/offers` adds an offer. Send `rate` as a percent and `payment_frequency` as
payments a year (`12` is monthly, `26` is bi-weekly).

```bash
curl -X POST https://api.mos.getbrokerplus.ca/v1/deals/cm9d1a2b3000/offers \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "First National 5-year fixed",
    "lender_slug": "first-national",
    "term_months": 60,
    "amortization_months": 300,
    "payment_frequency": 12,
    "mortgage_amount": 500000,
    "rate": 4.79,
    "fees": [{"label": "Appraisal", "amount": 450, "required_by_institution": true, "s48_included": true}]
  }'
```

`GET /v1/deals/{id}/offers/compare` is the tab's side-by-side comparison, worked out when you ask
from the offers, the scenarios, and today's rates. For each offer it has the payment, mortgage
default insurance, the penalty to break the term, the fees, and the annual percentage rate (APR).
Nothing in it is stored, so read it again after a change.

`PATCH /v1/deals/{id}/offers/{offerId}` changes the fields you send. `fees` replaces every fee.

## Deal scenarios

A scenario is a what-if on the deal: a property sold, debts paid out from the proceeds, and the
rates to try. `POST /v1/deals/{id}/scenarios` adds one, and the comparison prices it at each rate in
`rate_options`. A list you send in a `PATCH` replaces the stored list.

## Strategy analyses

A strategy analysis compares up to 8 mortgage options for a client, each measured against the one
at `baseline_index`, for example staying with the current lender against two switches. The broker
opens an analysis you save on the strategy board.

`POST /v1/strategy-analyses` saves one. Send each option's `rate` as a percent. For a readvanceable
mortgage, `readvanceable.limit` and `readvanceable.heloc_rate` are percents too.

```bash
curl -X POST https://api.mos.getbrokerplus.ca/v1/strategy-analyses \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Stay or switch",
    "deal_id": "cm9d1a2b3000",
    "options": [
      {"label": "Stay with TD", "balance": 400000, "rate": 5.24, "amortization_months": 300, "term_months": 60},
      {"label": "Switch to MCAP", "balance": 400000, "rate": 4.79, "amortization_months": 300, "term_months": 60}
    ]
  }'
```

`PATCH /v1/strategy-analyses/{id}` changes the fields you send. `options` replaces every option.
`GET /v1/strategy-analyses` lists analyses, and takes `deal_id` and `updated_since`.

BrokerPlus writes the note that explains the recommendation (`deal_defender`) in the app, where the
broker reviews it. You can read and edit the note through the API, but not ask BrokerPlus to write
one.