Copy page

Guides

Equity reports

An equity report tells a past client what their home is worth, what they owe, and how much equity they have, on a schedule. It keeps the broker in front of the client between deals. Over the API you can enroll clients, send a report now, pause or stop reports, and read what each client was sent.

How enrollment works

A report is about one deal: the client is the deal's primary applicant, and the property is its subject property. Every request on this page takes deal_ids, 1 to 100 of them. Find a client's deals with GET /v1/deals?contact_id=.

A report's settings live on the deal's opportunity: monthly_reports_enabled, monthly_reports_paused_at, and report_frequency. Read them with GET /v1/opportunities?deal_id=, or list everyone enrolled with GET /v1/opportunities?monthly_reports_enabled=true. A deal with no opportunity can still be enrolled; enrolling creates one.

Request	What it does
POST /v1/equity-reports/enroll	Starts recurring reports at a frequency.
POST /v1/equity-reports/resume	Starts paused reports again.
POST /v1/equity-reports/send	Sends one report now, by email or SMS.
POST /v1/equity-reports/pause	Pauses reports. The client stays enrolled.
POST /v1/equity-reports/unenroll	Stops reports.
POST /v1/equity-reports/frequency	Changes how often reports go out.

Each request happens now and returns 200, with one line in results for each deal you sent. Starting reports or sending one reaches a client, so a key with the no_sending limit can't do it (403 KEY_LIMITED), and if the broker your key acts as may not contact clients, you get 403 FORBIDDEN. Pausing, stopping, or changing the frequency can't send anything, so any key can do it.

Consent

The API follows the same rules as the reports page in BrokerPlus:

• A client who opted out of equity reports is refused with unsubscribed. Only the broker can enroll them again, in BrokerPlus.
• A client under a sanctions freeze is refused with frozen.
• A deal the broker dismissed from the book is refused with dismissed.
• Every time a report goes out, BrokerPlus checks the client's email or SMS consent again. A client who withdrew consent, or whose address is suppressed, doesn't get it.

These requests have no consent field, so you can't record consent or skip the check through them. Record or withdraw a client's consent with PATCH /v1/contacts/{id}/communication-preferences.

Enroll clients

Send the deals and a frequency: monthly (the default), quarterly, semi_annually, or annually.

The response is 200, with one line in results for each deal you sent.

Code
{
  "success": true,
  "data": {
    "results": [
      {
        "deal_id": "cmsdl1a2b",
        "opportunity_id": "cmsop7g8h",
        "contact_name": "Sam Client",
        "result": "changed",
        "reason": null
      },
      {
        "deal_id": "cmsdl3c4d",
        "opportunity_id": "cmsop9i0j",
        "contact_name": "Jordan Client",
        "result": "unchanged",
        "reason": "already_enrolled"
      },
      {
        "deal_id": "cmsdl5e6f",
        "opportunity_id": "cmsop1k2l",
        "contact_name": "Riley Client",
        "result": "refused",
        "reason": "unsubscribed"
      }
    ]
  }
}

The deals marked changed are enrolled now, and the first report goes out when it falls due. Enrolling doesn't send a report on the spot; call POST /v1/equity-reports/send too if you want one now. The other deals are not changed.

A changed deal can carry the reason no_email: the client is enrolled, but gets nothing until the broker adds an email address. If no deal can take the action, nothing changes: the response is 409 NOTHING_TO_REQUEST, with each deal's reason in error.details.results.

Send a report now

POST /v1/equity-reports/send sends one report to each client without enrolling anyone. Set channel to email (sent from the broker's connected mailbox) or sms (a text with a link to the report, with your own words in sms_body if you like).

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/equity-reports/send" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deal_ids":["cmsdl1a2b"],"channel":"email"}'

The response has the same shape as an enrollment. A deal marked changed got its report now. A client with no email address is refused with no_email, and for sms, one with no phone number with no_phone.

Pause, stop, or change the frequency

Each deal comes back changed, unchanged, or refused, and repeating a call is safe: the second one returns unchanged.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/equity-reports/pause" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deal_ids":["cmsdl1a2b","cmsdl7m8n"]}'

Code
{
  "success": true,
  "data": {
    "results": [
      {
        "deal_id": "cmsdl1a2b",
        "opportunity_id": "cmsop7g8h",
        "contact_name": "Sam Client",
        "result": "changed",
        "reason": null
      },
      {
        "deal_id": "cmsdl7m8n",
        "opportunity_id": null,
        "contact_name": null,
        "result": "refused",
        "reason": "not_found"
      }
    ]
  }
}

• POST /v1/equity-reports/pause keeps the client enrolled. Restart with POST /v1/equity-reports/resume.
• POST /v1/equity-reports/unenroll stops reports. Reports already sent stay readable.
• POST /v1/equity-reports/frequency takes frequency with deal_ids. It doesn't enroll anyone.

Change what the report shows

The report uses the figures on the deal's opportunity and property:

• Set the home's value with PATCH /v1/opportunities/{id} and property_value. It replaces the BrokerPlus estimate; send null to go back to the estimate.
• Correct the balance or rate with PATCH /v1/opportunities/{id} and balance or interest_rate (a percent, see Units).
• Split the mortgage with PATCH /v1/opportunities/{id} and segments, for example a fixed portion beside a line of credit. The list replaces every segment, so send each one you want to keep, or [] to make it one loan again. The first segment that is not a heloc sets the opportunity's product, rate and term. A deal in a locked stage refuses the change with 403 DEAL_LOCKED.
• Change the address with PATCH /v1/deals/{id}/property.

Read the reports that went out

GET /v1/equity-reports lists the reports clients received, newest first, with the figures exactly as the client saw them. ltv is a percent, like every ratio in the API. channel says whether it went by email or sms, viewed_at is when the client opened it, and cta_clicked_at is when they asked the broker to call.

Read the send and open history

A report is made once a month for each deal, and it can go out more than once. Two lists tell you what happened after that:

• GET /v1/equity-reports/sends lists each time a report went out: to which client, on which channel, at what frequency (null for a one-off send), and whether it left BrokerPlus (status is sent, failed, or suppressed). It is the same history as Outreach History in BrokerPlus.
• GET /v1/equity-reports/interactions lists what clients did with a report. field is email_open, page_view, or cta_click, or the figure the client corrected (propertyAddress, propertyValue, or mortgageBalance) with old_value, new_value, and the equity and loan-to-value the report showed after the correction.

Both are logs: a row never changes after it is written. To sync, send updated_since, and with it after_id from the last row you read. The rows come oldest first.

Code
curl "https://api.mos.getbrokerplus.ca/v1/equity-reports/interactions?field=cta_click&updated_since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY"

Answer a client's correction

A client can correct their report: the property's address, its value, or the mortgage balance. When the brokerage reviews corrections, or the deal's client data is locked, the correction waits for the broker, as on the report changes queue in BrokerPlus.

• GET /v1/equity-report-changes?status=pending lists the corrections that wait. old_value is what the report said and new_value is what the client says. held_reason says why it waited.
• POST /v1/equity-report-changes/{id}/accept writes the client's figure onto the deal.
• POST /v1/equity-report-changes/{id}/decline keeps the deal's figure. A declined property value is taken back off the client's report.

Neither sends anything to the client. A correction can be answered once: a second answer gets 404. Accepting on a deal whose client data is locked to another broker gets 403.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/equity-report-changes/cmt5e2r8k0003p3iu7h1c9d2a/accept" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY"

Retention signals

A retention signal is a reason BrokerPlus raised to reach a past client now: an equity signal when their loan-to-value fell below the brokerage's line, or a date of theirs (mortgage_anniversary, birthday, or new_year). GET /v1/pulse-signals lists them, newest first. Filter by type, status, contact_id, or deal_id. A drafted signal has a draft waiting for the broker: read it with GET /v1/drafts/{id} using draft_id, and approve it as any other draft.

GET /v1/pulse-triggers lists the broker's date triggers: the message for each date, how many days before or after it they go out, and whether they send on their own (auto_send). The broker has at most one trigger for each date.

POST /v1/pulse-triggers sets one up, switched off, with the type and an optional days_offset from -90 to 90. PATCH /v1/pulse-triggers/{id} moves days_offset. POST /v1/pulse-triggers/{id}/turn-on turns it on, and from then on BrokerPlus writes to each of the broker's clients on that date, so a key with the no_sending limit is refused it. POST /v1/pulse-triggers/{id}/turn-off turns it off. A message it already scheduled, up to a week ahead, still goes out. The message and auto_send are set in BrokerPlus, and there is no delete: turn the trigger off instead.

Errors

Status	Code	What to do
400	VALIDATION_ERROR	Send deal_ids as an array of 1 to 100 ids. details names the field.
403	KEY_LIMITED	The key has the no_sending limit. Use a key without it.
403	POLICY_BLOCKED	The brokerage's automation policy doesn't allow the request.
409	NOTHING_TO_REQUEST	No deal can take the action. Read error.details.results.