Copy page

Guides

Ask a client for something

This page covers the four things you can ask of the people on a deal: send documents, understand their conditions, sign forms, and read a letter such as an approval letter. Each request does exactly what the same button does in BrokerPlus.

Each request goes out now, as the broker your key acts as. A key with the no_sending limit can't make these requests (403 KEY_LIMITED). If that broker may not contact clients, you get 403 FORBIDDEN. If BrokerPlus can't send, you get 409 NOT_SENT, and nothing goes out.

Request	Response
POST /v1/deals/{id}/document-requests	201 with the document requests
POST /v1/deals/{id}/condition-requests	201 with the draft it went out
POST /v1/deals/{id}/signing-documents/send	200 with the signing documents
POST /v1/deals/{id}/signing-documents/{documentId}/resend	200 with the signing document
POST /v1/deals/{id}/generated-documents/{documentId}/send	201 with the draft it went out

Request documents

POST /v1/deals/{id}/document-requests is the Request Documents window in BrokerPlus. Each document is added to the client's portal now, and each applicant it is for gets an email with their own link.

The deal needs a client portal, which the client gets when they send their intake back. Without one the request returns 409 NO_CLIENT_HUB, so send an intake first.

Document codes come from GET /v1/document-types. Set contact_id on a document to ask one applicant, or leave it out to ask every applicant on the portal.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/document-requests" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "document_type": "t4", "note": "The last two years." },
      { "document_type": "paystub", "contact_id": "cmsclk2a9", "required": false }
    ],
    "message": "Hi Sam, these are the last items the lender needs."
  }'

Code
{
  "success": true,
  "data": [
    {
      "object": "document_request",
      "id": "cmsdi9t3q0004:doc_paystub:cmsclk2a9",
      "label": "Pay stub",
      "document_type": "paystub",
      "required": false,
      "contact_id": "cmsclk2a9",
      "contact_name": "Sam Client",
      "is_primary_applicant": false,
      "rejected": false,
      "waiting_on_intake": false,
      "requested_at": "2026-10-07T14:20:00.000Z"
    }
  ],
  "pagination": { "total": 3, "page": 1, "page_size": 3, "total_pages": 1 }
}

The response is 201 and is shortened. It has one line for each document and each applicant this request asked: here the T4 for both applicants and the pay stub for Sam. GET /v1/deals/{id}/document-requests lists everything the client still owes.

A wrong document_type or contact_id returns 422 VALIDATION_ERROR, and details.fields names each one, for example documents.1.contact_id.

Ask from a request template

Send template_id to ask for the documents on one of the broker's request templates. Each document goes to the applicants the template names for it, and you can add more in documents in the same request.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/document-requests" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "cmsrt0a1b0002", "message": "Hi Sam, here is what the lender needs." }'

The template must ask only for documents. A template that also has questions, a form to sign, or an item that shows only for some answers returns 422 TEMPLATE_NOT_SENDABLE: send it from BrokerPlus.

Explain conditions to somebody on the deal

POST /v1/deals/{id}/condition-requests writes a plain-language letter about a deal's conditions. It is Request From Participant on the deal's Conditions tab in BrokerPlus. A borrower gets a request for what the lender needs. A professional on the deal, such as a realtor or a lawyer, gets an update on the file.

Take the conditions from GET /v1/deals/{id}/conditions and the person from GET /v1/deals/{id}/participants. They need an email address.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/condition-requests" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "condition_ids": ["cmsdc0n1d0007"], "contact_id": "cmsclk2a9" }'

Code
{
  "success": true,
  "data": {
    "object": "draft",
    "id": "cmsd0dr7k0010",
    "contact_id": "cmsclk2a9",
    "deal_id": "cmsdl4k2p",
    "channel": "email",
    "status": "sent",
    "subject": "One document we need for your mortgage",
    "communication_id": "cmsd0cm2v0011"
  }
}

The response is shortened. The letter goes out now, from the broker's connected email. BrokerPlus sends it through a draft in the broker's name, so the broker sees it in their drafts folder and in Sent. The response is 201 with that draft. To write your own words, send subject and body; the letter goes out exactly as written.

Send documents to sign

A deal's signing package is the set of forms people on the deal sign, such as a consent form. Each document is for one person. It is the Signing Package on the deal's Compliance tab in BrokerPlus.

1. List the presets (saved sets of documents) with GET /v1/deals/{id}/signing-presets.
2. Add documents with POST /v1/deals/{id}/signing-documents: the signer's contact_id, plus a preset_id or one requirement_id. Adding sends nothing.
3. Preview one with POST /v1/deals/{id}/signing-documents/{documentId}/preview. You get the filled PDF in pdf_base64, or 422 if it can't be sent as it is.
4. Send with POST /v1/deals/{id}/signing-documents/send. BrokerPlus fills in each document again from the deal as it is now, checks it, and emails each signer one link to their documents. The response is 200 with the documents, each with status sent.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/signing-documents" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "cmsclk2a9", "preset_id": "cmsdp2r7s0003" }'

curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/signing-documents/send" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document_ids": ["cmsdo1b8n0006"], "note": "Two short forms for your file." }'

GET /v1/deals/{id}/signing-documents shows where each signing is in status: not_sent, sent, viewed, borrower_signed, signed, declined, voided, or failed.

If a signer lost the email, POST /v1/deals/{id}/signing-documents/{documentId}/resend sends them a new link now. The response is 200 with the document.

If a document can't be filled in or checked, you get 409 NOT_SENT, and nothing is sent. A signing can't be canceled through the API.

Send a generated document

A generated document is a letter BrokerPlus makes from a template, such as an approval letter with the brokerage's logo and the broker's signature. Making one sends nothing.

1. List the templates with GET /v1/document-templates.
2. Make the document with POST /v1/deals/{id}/generated-documents, with contact_id set to the person it is addressed to. BrokerPlus files the PDF on the deal and returns status final and its document_id.
3. Send it with POST /v1/deals/{id}/generated-documents/{documentId}/send. BrokerPlus emails it now, from the broker's connected email, with the PDF attached. The response is 201 with the draft it went out through, with status sent.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/generated-documents" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "cmsdt3m1p0002", "contact_id": "cmsclq7w3" }'

curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/generated-documents/cmsdg8k4r0005/send" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "cmsclk2a9" }'

If the broker has to fix something first, such as a missing signature, the document stays a draft and issues says what. A draft can't be sent (409 DOCUMENT_NOT_FINAL) until the broker fixes it in BrokerPlus.

To write your own email, send subject and body. A key with the no_documents limit can't use generated documents at all.

Ask a client for a score

A Net Promoter Score (NPS) survey asks one question: how likely is the client to recommend the broker, from 0 to 10. POST /v1/nps-surveys emails it to a client now, from the broker's connected email. Send email to use an address other than the one on the contact; that address replaces the contact's email, as it does in BrokerPlus.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/nps-surveys" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "cmsclq7w3", "deal_id": "cmsdl4k2p", "message": "Thanks for trusting us with your mortgage." }'

The response is 201 with the survey. After the client answers, GET /v1/nps-surveys?responded_since=2026-10-01T00:00:00Z lists each answer with its score, band (detractor, passive, or promoter), and comment. The brokerage's NPS alert rules decide who hears about each score.

A client with no email address and no email gets 400 NO_EMAIL. A broker with no email connected gets 412 EMAIL_NOT_CONNECTED.

Ask a client to declare PEP status

FINTRAC asks the broker to find out if a client is a politically exposed person (PEP), a family member of one, or the head of an international organization. The PEP declaration form asks the client and records the client's signature. POST /v1/pep-forms emails the form to a client now, from the broker's connected email. The form goes to the email address on the contact, and the link works for 30 days.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/pep-forms" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "cmsclq7w3", "application_number": "APP-20431" }'

The response is 201 with the form. GET /v1/pep-forms?status=submitted lists the forms that came back, with is_pep and pep_type. Only the broker who sent the form and a compliance reviewer get the other answers, in answers, as in BrokerPlus.

Only the broker assigned to the client, or an admin, can send the form (403 FORBIDDEN). A client with no email address gets 400 MISSING_EMAIL, and a client with no first or last name gets 400 MISSING_NAME.

Ask a borrower for consent

A borrower who did not fill in an intake has not given the consents that the intake collects. POST /v1/deals/{id}/consent-forms emails a borrower on the deal a form for one scope now, for example credit_pull or privacy_processing. The borrower signs by typing their name. Send email to use an address other than the one on the contact; that address replaces the contact's email, as it does in BrokerPlus.

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/deals/cmsdl4k2p/consent-forms" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "cmsclq7w3", "scope": "credit_pull" }'

The response is 201 with a consent_request. Its kind is consent_form, and its id is the form. When the borrower signs, the form's status is submitted, and consent_id names the consent that GET /v1/deals/{id}/consents now lists. For credit_pull, when the brokerage uploaded its own credit consent form in BrokerPlus, the borrower gets that form to sign in an intake instead. Then kind is intake, id is the intake, and no consent form is listed.

A borrower with no email address and no email gets 400 NO_EMAIL. A broker with no email connected gets 412 EMAIL_NOT_CONNECTED.

Request templates

A request template is a list of things to ask a client for: answers, documents, and forms to sign. The broker keeps them in the request library in BrokerPlus, and a team shares its broker's library. Building a template sends nothing to anyone. To ask a client for the documents on one, send its template_id to POST /v1/deals/{id}/document-requests.

Request	What it does
GET /v1/request-templates	Lists the library.
GET /v1/request-templates/{id}	Reads one template, with its items in order.
POST /v1/request-templates	Adds an empty template.
PATCH /v1/request-templates/{id}	Renames it, moves it to a shelf, or turns its public link on or off.
DELETE /v1/request-templates/{id}	Removes it from the library.
POST /v1/request-templates/{id}/duplicate	Copies it, with all its items.
POST /v1/request-templates/{id}/favourite	Stars it for the broker your key acts as. unfavourite removes it.
POST /v1/request-templates/{id}/reset	Puts a template that BrokerPlus supplies back the way it came.
POST /v1/request-templates/{id}/items	Adds an item.
PATCH /v1/request-templates/{id}/items/{itemId}	Changes an item.
DELETE /v1/request-templates/{id}/items/{itemId}	Removes an item.
POST /v1/request-templates/{id}/items/reorder	Sets the order of the items.
POST /v1/request-templates/{id}/items/{itemId}/reset	Puts one item back the way BrokerPlus wrote it.

Make a template, then add a document to ask for. A doc_request needs a document_type from GET /v1/document-types:

Code
curl -X POST "https://api.mos.getbrokerplus.ca/v1/request-templates" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Self-employed renewal", "category": "self_employed" }'

curl -X POST "https://api.mos.getbrokerplus.ca/v1/request-templates/cmsrt0a1b0002/items" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "doc_noa", "kind": "doc_request", "label": "Notice of assessment", "document_type": "noa" }'

A changed template applies to the next request sent from it. Requests that were sent before do not change. To add a form to sign, use BrokerPlus: the form needs its PDF.