# 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](/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. ```bash 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." }' ``` ```json { "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](#request-templates). Each document goes to the applicants the template names for it, and you can add more in `documents` in the same request. ```bash 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. ```bash 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" }' ``` ```json { "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`. ```bash 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`. ```bash 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. ```bash 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](/workspace#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. ```bash 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. ```bash 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`](#ask-from-a-request-template). | 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`: ```bash 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.